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
format	bson	Creates BSON parser / generator
binaryFormat	base64	Uses MIME Base64 encoding fo binary
binaryFormat	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.