JSONCoder

Description

Jsonex JSONCoder is a light-weight generic object serialization / deserialization library similar to Jackson, GSON or FastJson. This library has been widely used in various eBay projects for years. It's not a replacement for other popular libraries. But it solves some specific problems which are not available or not well-supported in other alternatives.

Why JSONCoder

There are plenty of options for JSON serialization/deserialization libraries, why we need another one? If you are also a fan of JSON, but hate the restrictions by JSON standards that make it so hard to be used as a configuration format, but still don't want to give up JSON to YAML (JSON is nice, why need Yet Another pretty ugly Markup Language). You can have a try of this library. This library focuses on solving following problems well:

Supports JSON extension proposal (JSONEX) which will make it friendly for configuration, such as
- comments support
- quote of key/value is optional
- customize quote characters (Avoid un-necessary escapes by choosing different quote characters like Javascript)
- multi-line string literal as in ES6
- Merge of config files (e.g. environment specific config override common config)
- Optional top level "[", "{" brackets
Supports serialization of arbitrary java objects out of box by detecting cyclic object references. You don't have to write serializer friendly classes or use any custom annotations to pollute your domain models. Whatever you have, it's supported.
Make sensible default over configuration. Minimize annotation or configuration usage. Such as it silently ignores unknown properties by default for forward compatibility
Focuses on developer friendly APIs at the same time still provides flexible configurations

Features

Auto-detect cyclic references and serialize the reference to avoid stack overflow
Options to include class fields in addition to getters
Pluggable custom encoder and decoder
Pluggable custom filters to exclude or mask fields for particular types
Options to skip certain classes
Options to skip sub-class fields
Options to filter fields based on certain attributes such as: private fields, enum names, readonly fields, etc
Custom date format and fallback date format during deserialization
Polymorphic types with "$type" attribute during deserialization
Generic types during deserialization
Deserialize and append to existing object (Incremental decoding, could be used to merge multiple config files)
Supports nested JSON String within JSON as normal sub JSON Object instead of serialized json string to avoid un-necessary escape in String literal
Supports forward compatibility features: silently ignore unknown properties, use @DefaultEnum to annotate a default enum which be used if unknown enum value is encountered
Supports proposed json extension format (JSONEX), Example in test
JDK version: 1.7 or above

And many more, please refer the class JSONCoderOption for more details.

Please refer the unit test class for more detailed usage patterns: JSONCoderTest

Usage

Maven Dependencies

 <dependency>
   <groupId>org.jsonex</groupId>
   <artifactId>JSONCoder</artifactId>
   <version>${jsonCoderVersion}</version>
 </dependency>

You can get current version by searching maven central

Simple Serialization / Deserialization

  // serialization
  JSONCoder.global.encode(o)
  // de-serialization
  SomeClass obj = JSONCoder.global.decode(str, SomeClass.class);

Filter out fields and classes

JSONCoderOption opt = new JSONCoderOption();
// For TestBean2 and it's sub-classes, only include field: "enumField2", "testBean"
opt.addFilterFor(TestBean2.class, include("enumField2", "testBean"));("field1ForClass1", "field2ForClass1");
// For TestBean, exclude field: "publicStrField"
opt.addFilterFor(TestBean.class, exclude("publicStrField"));
// For any class, exclude field: "fieldInAnyClass"
opt.getDefaultFilter().addProperties("fieldInAnyClass");
// Exclude certain classes
opt.addSkippedClasses(SomeExcludedClass.class);
String result = JSONCoder.encode(bean, opt);

Mask out certain fields: for privacy reason, quite often when we serialize an object, we need to maskout certain fields such as emailAddress, here's example to do that:
```
String result = JSONCoder.encode(bean, JSONCoderOption.ofIndentFactor(2).addFilterFor(SomeBean.class, mask("field1", "field2")));
```

Deserialize with generic types

String str = "['str1', 'str2', 'str3']";
List<String> result = JSONCoder.global.decode(new DecodeReq<List<String>>(){}.setSource(str));

Deserialize and merge to existing object (Incremental decode)

TestBean bean = JSONCoder.global.decodeTo(jsonStr, bean);

Set custom Quote and custom indentations

JSONCoderOption opt = new JSONCoderOption();
opt.getJsonOption().setQuoteChar('`');
opt.getJsonOption().setIndentFactor(2);
String jsonStr = JSONCoder.global.encode(someObj, opt);

public class CoderBigInteger implements ICoder<BigInteger>{
  public Class<BigInteger> getType() {return BigInteger.class;}
  
  @Override public TDNode encode(BigInteger o, BeanCoderContext context, TDNode target) {
    return target.setValue(o.toString());
  }

  @Override public BigInteger decode(TDNode jsonNode, Type type, BeanCoderContext context) {
    return new BigInteger((String)jsonNode.getValue());
  }
}
JSONCoderOption opt = new JSONCoderOption()
  .addCoder(new CoderBigInteger());
String jsonStr = JSONCoder.global.encode(new BigInteger("1234"), opt);

Limitations and Future enhancements

Performance improvement
Support of variable placeholder in JSON doc

Tech blogs

Dependency Indirection with Injectable Factory

License

Use of this source code is governed by an MIT-style license that can be found in the LICENSE file or at https://opensource.org/licenses/MIT.

eBay/jsonex