0
# FASTJSON 2
1

2
FASTJSON 2 is a high-performance and easy-to-use Java JSON processing library with extreme performance that far exceeds other popular JSON libraries. It supports JDK 8+, includes JDK 11/17 optimizations, supports Record types, GraalVM Native-Image, Android 8+, Kotlin, JSON Schema, and introduces JSONB binary format support.
3

4
## Package Information
5

6
- **Package Name**: com.alibaba.fastjson2:fastjson2
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to pom.xml:
10
  ```xml
11
  <dependency>
12
      <groupId>com.alibaba.fastjson2</groupId>
13
      <artifactId>fastjson2</artifactId>
14
      <version>2.0.57</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java { .api }
21
import com.alibaba.fastjson2.JSON;
22
import com.alibaba.fastjson2.JSONObject;
23
import com.alibaba.fastjson2.JSONArray;
24
import com.alibaba.fastjson2.JSONPath;
25
import com.alibaba.fastjson2.JSONB;
26
import com.alibaba.fastjson2.TypeReference;
27
import com.alibaba.fastjson2.JSONValidator;
28
```
29

30
## Basic Usage
31

32
```java
33
import com.alibaba.fastjson2.JSON;
34
import com.alibaba.fastjson2.JSONObject;
35

36
// Parse JSON string to object
37
String json = "{\"name\":\"John\",\"age\":30}";
38
JSONObject obj = JSON.parseObject(json);
39
String name = obj.getString("name");
40
Integer age = obj.getInteger("age");
41

42
// Parse to custom Java object
43
User user = JSON.parseObject(json, User.class);
44

45
// Serialize object to JSON
46
User user = new User("John", 30);
47
String jsonString = JSON.toJSONString(user);
48

49
// Array handling
50
String arrayJson = "[{\"name\":\"John\"},{\"name\":\"Jane\"}]";
51
JSONArray array = JSON.parseArray(arrayJson);
52
List<User> users = JSON.parseArray(arrayJson, User.class);
53

54
// Generic type handling with TypeReference
55
String mapJson = "{\"key1\":{\"name\":\"John\"},\"key2\":{\"name\":\"Jane\"}}";
56
Map<String, User> userMap = JSON.parseObject(mapJson, new TypeReference<Map<String, User>>(){});
57

58
// JSON validation
59
boolean isValid = JSONValidator.from(json).validate();
60
```
61

62
## Architecture
63

64
FASTJSON 2 is built around several key components:
65

66
- **JSON Static Interface**: Primary entry point providing static methods for all JSON operations
67
- **JSONObject/JSONArray**: Enhanced Map/List implementations with type-safe getters and path access
68
- **Reader/Writer Framework**: Extensible deserialization/serialization system with ObjectReader/ObjectWriter interfaces
69
- **Annotation System**: Comprehensive annotations for customizing JSON processing behavior
70
- **Feature Configuration**: Fine-grained control through JSONReader.Feature and JSONWriter.Feature enums
71
- **JSONB Binary Format**: High-performance binary JSON format for optimized transmission and storage
72
- **JSONPath Support**: Advanced path-based JSON data extraction and manipulation
73
- **Schema Validation**: JSON Schema validation capabilities for data integrity
74

75
## Capabilities
76

77
### Core JSON Operations
78

79
Primary JSON parsing and serialization operations using the static JSON interface. Essential for all JSON processing tasks.
80

81
```java { .api }
82
public static Object parse(String text);
83
public static Object parse(String text, JSONReader.Feature... features);
84
public static JSONObject parseObject(String text);
85
public static <T> T parseObject(String text, Class<T> clazz);
86
public static JSONArray parseArray(String text);
87
public static <T> List<T> parseArray(String text, Class<T> clazz);
88
public static String toJSONString(Object object);
89
public static String toJSONString(Object object, JSONWriter.Feature... features);
90
public static byte[] toJSONBytes(Object object);
91
```
92

93
[Core JSON Operations](./core-operations.md)
94

95
### Data Structures
96

97
Enhanced JSONObject and JSONArray classes providing type-safe access methods and advanced functionality beyond standard Map/List interfaces.
98

99
```java { .api }
100
public class JSONObject extends LinkedHashMap<String, Object> {
101
    public String getString(String key);
102
    public Integer getInteger(String key);
103
    public JSONObject getJSONObject(String key);
104
    public JSONArray getJSONArray(String key);
105
    public Object getByPath(String jsonPath);
106
    public <T> T to(Class<T> clazz);
107
}
108

109
public class JSONArray extends ArrayList<Object> {
110
    public String getString(int index);
111
    public JSONObject getJSONObject(int index);
112
    public <T> T to(Class<T> clazz);
113
    public <T> List<T> toJavaList(Class<T> clazz);
114
}
115
```
116

117
[Data Structures](./data-structures.md)
118

119
### Annotations and Configuration
120

121
Comprehensive annotation system for customizing JSON serialization and deserialization behavior at class and field levels.
122

123
```java { .api }
124
@JSONField(name = "customName", format = "yyyy-MM-dd")
125
@JSONType(naming = PropertyNamingStrategy.SnakeCase)
126
@JSONCreator
127
@JSONBuilder
128
@JSONCompiled
129
```
130

131
[Annotations and Configuration](./annotations.md)
132

133
### Advanced Features
134

135
High-performance features including JSONB binary format, JSONPath queries, schema validation, and custom filters.
136

137
```java { .api }
138
public static byte[] toBytes(Object object); // JSONB
139
public static Object extract(String json, String path); // JSONPath
140
public static boolean isValid(String text, JSONSchema schema); // Schema
141
public static void config(Filter... filters); // Filters
142
```
143

144
[Advanced Features](./advanced-features.md)
145

146
### Reader/Writer Framework
147

148
Extensible framework for custom serialization and deserialization logic with ObjectReader and ObjectWriter interfaces.
149

150
```java { .api }
151
public interface ObjectReader<T> {
152
    T readObject(JSONReader jsonReader);
153
    Object createInstance();
154
}
155

156
public interface ObjectWriter<T> {
157
    void write(JSONWriter jsonWriter, Object object);
158
    boolean hasFilter();
159
}
160
```
161

162
[Reader/Writer Framework](./reader-writer.md)
163

164
## Type Definitions
165

166
```java { .api }
167
public enum JSONReader.Feature {
168
    FieldBased, SupportAutoType, SupportArrayToBean, 
169
    UseBigDecimalForFloats, UseBigDecimalForDoubles, TrimString, 
170
    AllowUnQuotedFieldNames, ErrorOnNullForPrimitives, UseNativeObject,
171
    SupportClassForName, InitStringFieldAsEmpty, AllowComment,
172
    AllowSingleQuotes, AllowUnQuotedFieldNames, SupportSmartMatch
173
}
174

175
public enum JSONWriter.Feature {
176
    WriteNulls, PrettyFormat, WriteClassName, BeanToArray,
177
    UseSingleQuotes, ReferenceDetection, WriteEnumsUsingName,
178
    WriteEnumsUsingToString, NotWriteHashMapArrayListClassName,
179
    NotWriteRootClassName, WriteBigDecimalAsPlain, WriteNonStringKeyAsString,
180
    WriteByteArrayAsBase64, WriteBooleanAsNumber, OptimizedForAscii
181
}
182

183
public enum PropertyNamingStrategy {
184
    CamelCase, PascalCase, SnakeCase, UpperCase,
185
    UpperCamelCaseWithSpaces, UpperCamelCaseWithUnderScores,
186
    UpperCamelCaseWithDashes
187
}
188

189
public abstract class TypeReference<T> {
190
    protected TypeReference() {}
191
    public Type getType() { return null; }
192
}
193

194
public class JSONValidator {
195
    public static JSONValidator from(String json);
196
    public static JSONValidator from(byte[] bytes);
197
    public boolean validate();
198
    public Type getType();
199
}
200

201
public class JSONException extends RuntimeException {}
202
public class JSONValidException extends JSONException {}
203

204
public class SymbolTable {
205
    public static SymbolTable of(String... symbols);
206
    public int getId(String symbol);
207
    public String getName(int id);
208
}
209

210
public interface PathCallback {
211
    void callback(String path, Object value);
212
}
213

214
public interface PropertyFilter {
215
    boolean apply(Object object, String name, Object value);
216
}
217
```