cookjson-core

cookjson-core currently contains parsers and generators for Json and BSON formats.

Maven

<dependency>
        <groupId>org.yuanheng.cookjson</groupId>
        <artifactId>cookjson-core</artifactId>
        <version>1.0</version>
</dependency>

CookJsonProvider

CookJsonProvider can be used to create JSON or BSON parsers or generators depending on the config settings. The parsers and generators created without config settings are JSON specific.

Property Name Value Description
format json Creates JSON parser / generator
bson Creates BSON parser / generator
binaryFormat base64 Uses MIME Base64 encoding fo binary
hex Uses hexadecimal format
comment true Enables comments in JSON
rootAsArray true Treats the root Document as array in BSON
useDouble true Stores BigDecimal / BigInteger as double in BSON

Examples 1: Creating a JsonParser for a JSON Document

CookJsonProvider provider = new CookJsonProvider ();
JsonParser p = provider.createParser (new FileInputStream (srcFile));

Examples 2: Creating a JsonParser for a JSON Document with Comments

JsonProvider provider = new CookJsonProvider ();
HashMap<String, Object> config = new HashMap<String, Object> ();
// Either Boolean.TRUE or "true" can be used.
config.put (CookJsonProvider.COMMENT, Boolean.TRUE);
JsonParser p = provider.createParserFactory (config).createParser (new FileInputStream (srcFile));

Examples 3: Creating a JsonParser for a BSON Document

JsonProvider provider = new CookJsonProvider ();
HashMap<String, Object> config = new HashMap<String, Object> ();
config.put (CookJsonProvider.FORMAT, CookJsonProvider.FORMAT_BSON);
JsonParser p = provider.createParserFactory (config).createParser (new FileInputStream (srcFile));

JSON

Parsers

  • TextJsonParser - A JSON parser with Reader as input.
  • UTFTextJsonParser - A very fast JSON parser specifically for UTF-8 input.

Generators

  • TextJsonGenerator - JSON output with compact format.
  • PrettyTextJsonGenerator - JSON output with indented format.

These classes are all public. So you can either directly construct them or use JsonProvider to create them.

It should be noted that the location unit returned by TextJsonParser is in characters, while the location unit returned by UTFTextJsonParser is in bytes.

Performance Tips

When parsing JSON inputs in UTF-8, use UTFTextJsonParser instead of TextJsonParser. It can be several times faster.

For example, instead of the following parser construction:

CookJsonProvider provider = new CookJsonProvider ();
JsonParser p = provider.createParser (new InputStreamReader (new FileInputStream (srcFile), "utf-8"));

The parsing is far more efficient using the following approach:

CookJsonProvider provider = new CookJsonProvider ();
JsonParser p = provider.createParser (new FileInputStream (srcFile), Charset.forName ("utf-8"));

BSON

BSON is a file format used by MongoDB. The main advantage of this particular file format is its native support for binary data. However, space-wise, it is not particularly efficient. It also contains a lot of MongoDB specific data types that are not useful to general audiences.

BsonParser

  • setRootArray(boolean) basically treats the root Document as an Array instead of an Object in JSON. It does not verify if the fields names are correct.

BsonGenerator

One major disadvantage of the file format is that every Document and Array type needs to have its length information generated. Here I follow Bson4Jackson ‘s approach to generate a stream format that contains 0``s for the length information.  One can call ``BsonFixLength.fix() function to correct the length information.

BsonGenerator generates a BSON file using a stream operation that does not have correct lengths for Document and Array types. This format is identical to Bson4Jackson stream output. This file can be parsed by BsonParser.

The length information can be fixed by calling BsonFixLength.fix() function.