README_EN.md

Language: 中文 | English

1. FASTJSON v2

FASTJSONv2 is an upgrade of the FASTJSON, with the goal of providing a highly optimized JSON library for the next ten years.

• Supports the JSON and JSONB Protocols
• Supports full parsing and partial parsing
• Supports Java servers and Android Clients, and has big data applications.

Related Documents:

• JSONB format documentation:
  https://github.com/alibaba/fastjson2/wiki/jsonb_format_cn
• FASTJSON v2's performance has been significantly improved. For the benchmark, see here:
  https://github.com/alibaba/fastjson2/wiki/fastjson_benchmark

2. Setup

2.1 Maven Build System

FASTJSONv2's groupId is different from versions 1.x, it is instead com.alibaba.fastjson2:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.2</version>
</dependency>

Find the latest version of FASTJSONv2at maven.org.

2.2 fastjson v1 Compatibility Package

If you are using fastjson 1.2.x, you can use the compatibility package. The compatibility package cannot guarantee 100% compatibility. Please test it yourself and report any problems.

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>2.0.2</version>
</dependency>

2.3 Best Practice

The package name of fastjson v2 is different from fastjson v1. It is com.alibaba.fastjson2. If you used fastjson v1 before, simply change the package name.

package com.alibaba.fastjson2;

class JSON {
    // Parse String into JSONObject
    static JSONObject parseObject(String str);

    // Parse a String into JSONArray
    static JSONArray parseArray(String str);

    // Parse a String into a Java Object
    static T parseObject(byte[] utf8Bytes, Class<T> objectClass);

    // Output a Java Object into a string
    static String toJSONString(Object object);

    // Output a Java Object into a JSON Byte Array
    static byte[] toJSONBytes(Object object);
}

class JSONB {
    // Parse a JSONB byte array into a Java Object
    static T parseObject(byte[] jsonbBytes, Class<T> objectClass);

    // Convert a Java Object into a JSONB Byte Array
    static byte[] toBytes(Object object);
}

class JSONObject {
    Object get(String key);
    int getIntValue(String key);
    Integer getInteger(String key);
    long getLongValue(String key);
    Long getLong(String key);
    T getObject(String key, Class<T> objectClass);

    // Convert JSONObject into a Java Object
    T toJavaObject(Class<T> objectClass);
}

class JSONArray {
    Object get(int index);
    int getIntValue(int index);
    Integer getInteger(int index);
    long getLongValue(int index);
    Long getLong(int index);
    T getObject(int index, Class<T> objectClass);
}

class JSONPath {
    // Construct a JSONPath
    static JSONPath of(String path);

    // The input is directly parsed according to the path,
    // which will be parsed and optimized but not fully parsed.
    Object extract(JSONReader jsonReader);

    // Evaluate object based on the path
    Object eval(Object rootObject);
}

class JSONReader {
    // Constructs a JSONReader given a JSON String
    static JSONReader of(String str);

    // Constructs a JSONReader given a UTF-8 encoded byte array
    static JSONReader of(byte[] utf8Bytes);

    // Construct a JSONReader given a char array
    static JSONReader of(char[] chars);

    // Construct a JSONReader given a JSONB-formatted byte array
    static JSONReader ofJSONB(byte[] jsonbBytes);
}

3. Reading a JSON Object

String str = "{\"id\":123}";
JSONObject jsonObject = JSON.parseObject(str);
int id = jsonObject.getIntValue("id");

String str = "[\"id\", 123]";
JSONArray jsonArray = JSON.parseArray(str);
String name = jsonArray.getString(0);
int id = jsonArray.getIntValue(1);

4. Generate JSON using a JavaBean object

4.1 Generating a JSON String using JavaBean

class Product {
    public int id;
    public String name;
}

Product product = new Product();
product.id = 1001;
product.name = "DataWorks";

JSON.toJSONString(product);

// Produces the following result
{
    "id"   : 1001,
    "name" : "DataWorks"
}

JSON.toJSONString(product, JSONWriter.Feature.BeanToArray);
// Produces the following result
[1001, "DataWorks"]

4.2 Generating a UTF-8 encoded byte array from a JavaBean Object

Product product = ...;
byte[] utf8JSONBytes = JSON.toJSONBytes(product);

4.3 将JavaBean对象生成JSONB格式的byte[]

Product product = ...;
byte[] jsonbBytes = JSONB.toBytes(product);

byte[] jsonbBytes = JSONB.toBytes(product, JSONWriter.Feature.BeanToArray);

5. Reading JSON using JavaBean

5.1 Reading a String using JavaBean

String str = "{\"id\":123}";
Product product = JSON.parseObject(str, Product.class);

5.2 Reading a UTF-8encoded byte array with JavaBean

byte[] utf8Bytes = "{\"id\":123}".getBytes(StandardCharsets.UTF_8);
Product product = JSON.parseObject(utf8Bytes, Product.class);

5.3 Reading JSONB data with JavaBean

byte[] jsonbBytes = ...
Product product = JSONB.parseObject(jsonbBytes, Product.class);

Product product = JSONB.parseObject(jsonbBytes, Product.class, JSONReader.Feature.SupportBeanArrayMapping);

6. Using JSONPath

6.1 Use JSONPath selection to read data

String str = ...;

// Caching and Reusing can improve performance
JSONPath path = JSONPath.of("$.id"); 

JSONReader parser = JSONReader.of(str);
Object result = path.extract(parser);

6.2 Reading partial utf8Bytes data using JSONPath

byte[] utf8Bytes = ...;

// Caching and Reusing can improve perforamance
JSONPath path = JSONPath.of("$.id"); 

JSONReader parser = JSONReader.of(utf8Bytes);
Object result = path.extract(parser);

6.3 Reading partial jsonbBytes data using JSONPath

byte[] jsonbBytes = ...;

// Caching and Reusing can improve performance
JSONPath path = JSONPath.of("$.id");

// Note that this is using the ofJSONB method
JSONReader parser = JSONReader.ofJSONB(jsonbBytes); 
Object result = path.extract(parser);