Master FastJSON 2.0: Maven Setup, Core APIs, and JSONPath Guide

FastJSON 2.0 is a major upgrade of the FastJSON project, aiming to provide a high‑performance JSON library for the next decade. It supports both JSON and JSONB protocols with a single API, treats JSONPath as a first‑class citizen, and works on Java servers, Android clients, and big‑data scenarios.

FastJSON 2 code: https://github.com/alibaba/fastjson2/releases/tag/2.0.1

JSONB format documentation: https://github.com/alibaba/fastjson2/wiki/jsonb_format_cn

Performance benchmarks: https://github.com/alibaba/fastjson2/wiki/fastjson_benchmark

2. Preparation

2.1 Maven Dependency

In FastJSON 2.0 the groupId has changed to com.alibaba.fastjson2.

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

Repository: https://repo1.maven.org/maven2/com/alibaba/fastjson2/fastjson2/

2.2 Compatibility Package

If you are upgrading from FastJSON 1.2.x, you can use the compatibility package, but it does not guarantee 100% compatibility; thorough testing is required.

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

2.3 Common Classes and Methods

The package name for FastJSON 2.0 is com.alibaba.fastjson2. Most code works by simply changing the package name.

package com.alibaba.fastjson2;

class JSON {
    // Parse a JSON string into JSONObject
    static JSONObject parseObject(String str);
    // Parse a JSON string into JSONArray
    static JSONArray parseArray(String str);
    // Parse UTF‑8 bytes into a Java object
    static T parseObject(byte[] utf8Bytes, Class<T> objectClass);
    // Serialize a Java object to JSON string
    static String toJSONString(Object object);
    // Serialize a Java object to UTF‑8 bytes
    static byte[] toJSONBytes(Object object);
}

class JSONB {
    // Parse JSONB bytes into a Java object
    static T parseObject(byte[] jsonbBytes, Class<T> objectClass);
    // Serialize a Java object to JSONB bytes
    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);
    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 {
    // Create a JSONPath instance
    static JSONPath of(String path);
    // Extract data using a JSONReader (partial parsing)
    Object extract(JSONReader jsonReader);
    // Evaluate a path against a Java object
    Object eval(Object rootObject);
}

class JSONReader {
    // Create a reader from a String
    static JSONReader of(String str);
    // Create a reader from UTF‑8 bytes
    static JSONReader of(byte[] utf8Bytes);
    // Create a reader from a char array
    static JSONReader of(char[] chars);
    // Create a reader for JSONB bytes
    static JSONReader ofJSONB(byte[] jsonbBytes);
}

3. Reading JSON Objects

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

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

4. Serializing JavaBeans

4.1 Serialize to JSON String

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

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

String json = JSON.toJSONString(product);
// Result: {"id":1001,"name":"DataWorks"}

String jsonArray = JSON.toJSONString(product, JSONWriter.Feature.BeanToArray);
// Result: [1001,"DataWorks"]

4.2 Serialize to UTF‑8 Bytes

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

4.3 Serialize to JSONB Bytes

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

5. Deserializing to JavaBeans

5.1 From JSON String

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

5.2 From UTF‑8 Bytes

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

5.3 From JSONB Bytes

byte[] jsonbBytes = ...;
Product product = JSONB.parseObject(jsonbBytes, Product.class);
// With additional feature support
Product product2 = JSONB.parseObject(jsonbBytes, Product.class, JSONReader.Feature.SupportBeanArrayMapping);

6. Using JSONPath

6.1 Partial Read from String

String str = ...;
JSONPath path = JSONPath.of("$.id"); // cache for reuse
JSONReader parser = JSONReader.of(str);
Object result = path.extract(parser);

6.2 Partial Read from UTF‑8 Bytes

byte[] utf8Bytes = ...;
JSONPath path = JSONPath.of("$.id");
JSONReader parser = JSONReader.of(utf8Bytes);
Object result = path.extract(parser);

6.3 Partial Read from JSONB Bytes

byte[] jsonbBytes = ...;
JSONPath path = JSONPath.of("$.id");
JSONReader parser = JSONReader.ofJSONB(jsonbBytes); // note the ofJSONB method
Object result = path.extract(parser);