README_EN.md

Language: 中文 | English

FASTJSON v2

FASTJSONv2 is an upgrade of the FASTJSON, with the goal of providing a highly optimized JSON librarray 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.
• Supports Kotlin

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

1. Prepare

1.1 Download

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

Maven:

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

Gradle:

dependencies {
    implementation 'com.alibaba.fastjson2:fastjson2:2.0.3'
}

Find the latest version of FASTJSONv2 at maven.org.

1.2 Compatible

Compatible dependence of fastjson-v1

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.3</version>
</dependency>

Gradle:

dependencies {
    implementation 'com.alibaba:fastjson:2.0.3'
}

Compatible dependence of fastjson-kotlin

If your project uses kotlin, you can use the Fastjson-Kotlin module, and use the characteristics of kotlin.

Maven:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-kotlin</artifactId>
    <version>2.0.3</version>
</dependency>

Kotlin Gradle:

dependencies {
    implementation("com.alibaba.fastjson2:fastjson2-kotlin:2.0.3")
}

2 Usage

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.

2.1 Parse JSON into JSONObject

Java:

String text = "...";
JSONObject data = JSON.parseObject(text);

byte[] bytes = ...;
JSONObject data = JSON.parseObject(bytes);

Kotlin:

import com.alibaba.fastjson2.*

val text = ... // String
val data = text.parseObject()

val bytes = ... // ByteArray
val data = bytes.parseObject() // JSONObject

2.2 Parse JSON into JSONArray

Java:

String text = "...";
JSONArray data = JSON.parseArray(text);

Kotlin:

import com.alibaba.fastjson2.*

val text = ... // String
val data = text.parseArray() // JSONArray

2.3 Parse JSON into a Java Object

Java:

String text = "...";
User data = JSON.parseObject(text, User.class);

Kotlin:

import com.alibaba.fastjson2.*

val text = ... // String
val data = text.to<User>() // User
val data = text.parseObject<User>() // User

2.4 Serialization Java Object to JSON

Java:

Object data = "...";
String text = JSON.toJSONString(data);
byte[] text = JSON.toJSONBytes(data);

Kotlin:

import com.alibaba.fastjson2.*

val data = ... // Any
val text = text.toJSONString() // String
val bytes = text.toJSONByteArray() // ByteArray

2.5 Use JSONObject、JSONArray

2.5.1 Get simple property

String text = "{\"id\": 2,\"name\": \"fastjson2\"}";
JSONObject obj = JSON.parseObject(text);

int id = obj.getIntValue("id");
String name = obj.getString("name");

String text = "[2, \"fastjson2\"]";
JSONArray array = JSON.parseArray(text);

int id = array.getIntValue(0);
String name = array.getString(1);

2.5.2 Get JavaBean

Java:

JSONArray array = ...
JSONObject obj = ...

User user = array.getObject(0, User.class);
User user = obj.getObject("key", User.class);

Kotlin:

val array = ... // JSONArray
val obj = ... // JSONObject

val user = array.getObject<User>(0)
val user = obj.getObject<User>("key")

2.5.3 Convert to JavaBean

Java:

JSONArray array = ...
JSONObject obj = ...

User user = obj.toJavaObject(User.class);
List<User> users = array.toJavaList(User.class);

Kotlin:

val array = ... // JSONArray
val obj = ... // JSONObject

val user = obj.toObject<User>() // User
val users = array.toList<User>() // List<User>

2.6 Serialize JavaBean to JSON

Java:

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

User user = new User();
user.id = 2;
user.name = "FastJson2";

String text = JSON.toJSONString(user);
byte[] bytes = JSON.toJSONBytes(user);

Kotlin:

class User(
    var id: Int,
    var name: String
)

val user = User()
user.id = 2
user.name = "FastJson2"

val text = user.toJSONString() // String
val bytes = user.toJSONByteArray() // ByteArray

Serialization result:

{
    "id"   : 2,
    "name" : "FastJson2"
}

3. Advanced usage

3.1 Use JSONB

3.1.1 Serialize JavaBean to JSONB

User user = ...;
byte[] bytes = JSONB.toBytes(user);
byte[] bytes = JSONB.toBytes(user, JSONWriter.Feature.BeanToArray);

3.1.2 Parse JSONB to JavaBean

byte[] bytes = ...
User user = JSONB.parseObject(bytes, User.class);
User user = JSONB.parseObject(bytes, User.class, JSONReader.Feature.SupportBeanArrayMapping);

3.2 Use JSONPath

3.2.1 Use JSONPath to read partial data

String text = ...;
JSONPath path = JSONPath.of("$.id"); // Cached for reuse

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

3.2.2 Read part of byte[] data using JSONPath

byte[] bytes = ...;
JSONPath path = JSONPath.of("$.id"); // Cached for reuse

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

3.2.3 Read part of byte[] data using JSONPath

byte[] bytes = ...;
JSONPath path = JSONPath.of("$.id"); // Cached for reuse

JSONReader parser = JSONReader.ofJSONB(bytes); // Use ofJSONB method
Object result = path.extract(parser);