0
# Data Structures
1

2
Enhanced JSONObject and JSONArray classes providing type-safe access methods and advanced functionality beyond standard Map/List interfaces. These classes offer optimized JSON-specific operations and seamless conversion capabilities.
3

4
## Capabilities
5

6
### JSONObject
7

8
Enhanced LinkedHashMap implementation with type-safe getters, JSONPath support, and conversion utilities.
9

10
```java { .api }
11
/**
12
 * JSON object implementation extending LinkedHashMap
13
 */
14
public class JSONObject extends LinkedHashMap<String, Object> implements InvocationHandler {
15
    
16
    /**
17
     * Get string value by key
18
     * @param key Property key
19
     * @return String value or null
20
     */
21
    public String getString(String key);
22
    
23
    /**
24
     * Get integer value by key
25
     * @param key Property key
26
     * @return Integer value or null
27
     */
28
    public Integer getInteger(String key);
29
    
30
    /**
31
     * Get long value by key
32
     * @param key Property key
33
     * @return Long value or null
34
     */
35
    public Long getLong(String key);
36
    
37
    /**
38
     * Get double value by key
39
     * @param key Property key
40
     * @return Double value or null
41
     */
42
    public Double getDouble(String key);
43
    
44
    /**
45
     * Get primitive double value by key
46
     * @param key Property key
47
     * @return double value or 0.0 if null
48
     */
49
    public double getDoubleValue(String key);
50
    
51
    /**
52
     * Get primitive long value by key  
53
     * @param key Property key
54
     * @return long value or 0L if null
55
     */
56
    public long getLongValue(String key);
57
    
58
    /**
59
     * Get primitive int value by key
60
     * @param key Property key
61
     * @return int value or 0 if null
62
     */
63
    public int getIntValue(String key);
64
    
65
    /**
66
     * Get primitive boolean value by key
67
     * @param key Property key
68
     * @return boolean value or false if null
69
     */
70
    public boolean getBooleanValue(String key);
71
    
72
    /**
73
     * Get boolean value by key
74
     * @param key Property key
75
     * @return Boolean value or null
76
     */
77
    public Boolean getBoolean(String key);
78
    
79
    /**
80
     * Get nested JSONObject by key
81
     * @param key Property key
82
     * @return JSONObject or null
83
     */
84
    public JSONObject getJSONObject(String key);
85
    
86
    /**
87
     * Get JSONArray by key
88
     * @param key Property key
89
     * @return JSONArray or null
90
     */
91
    public JSONArray getJSONArray(String key);
92
    
93
    /**
94
     * Get List value by key
95
     * @param key Property key
96
     * @return List or null
97
     */
98
    public List getList(String key);
99
    
100
    /**
101
     * Access nested values using JSONPath expression
102
     * @param jsonPath Path expression (e.g., "$.user.name")
103
     * @return Value at specified path
104
     */
105
    public Object getByPath(String jsonPath);
106
    
107
    /**
108
     * Convert to specific Java class
109
     * @param clazz Target class type
110
     * @return Instance of specified class
111
     */
112
    public <T> T to(Class<T> clazz);
113
    
114
    /**
115
     * Convert to Java object (alias for to())
116
     * @param clazz Target class type
117
     * @return Instance of specified class
118
     */
119
    public <T> T toJavaObject(Class<T> clazz);
120
    
121
    /**
122
     * Iterate over array objects in this JSONObject
123
     */
124
    public void forEachArrayObject();
125
}
126
```
127

128
### JSONArray
129

130
Enhanced ArrayList implementation with type-safe getters and conversion utilities for JSON arrays.
131

132
```java { .api }
133
/**
134
 * JSON array implementation extending ArrayList
135
 */
136
public class JSONArray extends ArrayList<Object> {
137
    
138
    /**
139
     * Get string value by index
140
     * @param index Array index
141
     * @return String value or null
142
     */
143
    public String getString(int index);
144
    
145
    /**
146
     * Get integer value by index
147
     * @param index Array index
148
     * @return Integer value or null
149
     */
150
    public Integer getInteger(int index);
151
    
152
    /**
153
     * Get long value by index
154
     * @param index Array index
155
     * @return Long value or null
156
     */
157
    public Long getLong(int index);
158
    
159
    /**
160
     * Get double value by index
161
     * @param index Array index
162
     * @return Double value or null
163
     */
164
    public Double getDouble(int index);
165
    
166
    /**
167
     * Get primitive double value by index
168
     * @param index Array index
169
     * @return double value or 0.0 if null
170
     */
171
    public double getDoubleValue(int index);
172
    
173
    /**
174
     * Get primitive long value by index
175
     * @param index Array index
176
     * @return long value or 0L if null
177
     */
178
    public long getLongValue(int index);
179
    
180
    /**
181
     * Get primitive int value by index
182
     * @param index Array index
183
     * @return int value or 0 if null
184
     */
185
    public int getIntValue(int index);
186
    
187
    /**
188
     * Get primitive boolean value by index
189
     * @param index Array index
190
     * @return boolean value or false if null
191
     */
192
    public boolean getBooleanValue(int index);
193
    
194
    /**
195
     * Get boolean value by index
196
     * @param index Array index
197
     * @return Boolean value or null
198
     */
199
    public Boolean getBoolean(int index);
200
    
201
    /**
202
     * Get nested JSONObject by index
203
     * @param index Array index
204
     * @return JSONObject or null
205
     */
206
    public JSONObject getJSONObject(int index);
207
    
208
    /**
209
     * Get nested JSONArray by index
210
     * @param index Array index
211
     * @return JSONArray or null
212
     */
213
    public JSONArray getJSONArray(int index);
214
    
215
    /**
216
     * Convert to specific Java class
217
     * @param clazz Target class type
218
     * @return Instance of specified class
219
     */
220
    public <T> T to(Class<T> clazz);
221
    
222
    /**
223
     * Convert to Java array
224
     * @return Object array
225
     */
226
    public Object[] toArray();
227
    
228
    /**
229
     * Convert to typed Java List
230
     * @param clazz Element class type
231
     * @return List of specified element type
232
     */
233
    public <T> List<T> toJavaList(Class<T> clazz);
234
    
235
    /**
236
     * Enhanced set method with negative indexing and auto-expansion
237
     * @param index Array index (supports negative indexing)
238
     * @param value Value to set
239
     * @return Previous value at index
240
     */
241
    public Object set(int index, Object value);
242
}
243
```
244

245
**Usage Examples:**
246

247
```java
248
import com.alibaba.fastjson2.JSON;
249
import com.alibaba.fastjson2.JSONObject;
250
import com.alibaba.fastjson2.JSONArray;
251

252
// JSONObject usage
253
String json = "{\"name\":\"John\",\"age\":30,\"active\":true,\"scores\":[95,87,92]}";
254
JSONObject obj = JSON.parseObject(json);
255

256
// Type-safe getters
257
String name = obj.getString("name");        // "John"
258
Integer age = obj.getInteger("age");        // 30
259
Boolean active = obj.getBoolean("active"); // true
260
JSONArray scores = obj.getJSONArray("scores");
261

262
// JSONPath access
263
String nestedJson = "{\"user\":{\"profile\":{\"name\":\"John\"}}}";
264
JSONObject nested = JSON.parseObject(nestedJson);
265
String userName = (String) nested.getByPath("$.user.profile.name"); // "John"
266

267
// Convert to custom object
268
User user = obj.to(User.class);
269

270
// JSONArray usage
271
String arrayJson = "[{\"name\":\"John\",\"age\":30},{\"name\":\"Jane\",\"age\":25}]";
272
JSONArray array = JSON.parseArray(arrayJson);
273

274
// Access by index
275
JSONObject firstUser = array.getJSONObject(0);
276
String firstName = firstUser.getString("name"); // "John"
277

278
// Convert to typed list
279
List<User> users = array.toJavaList(User.class);
280

281
// Enhanced set with negative indexing
282
JSONArray numbers = JSON.parseArray("[1,2,3,4,5]");
283
numbers.set(-1, 10); // Sets last element to 10: [1,2,3,4,10]
284

285
// Auto-expansion
286
JSONArray expandable = new JSONArray();
287
expandable.set(5, "value"); // Automatically expands to index 5
288
```
289

290
### Advanced JSONObject Features
291

292
```java
293
// Complex nested structure access
294
String complexJson = """
295
{
296
  "users": [
297
    {"name": "John", "addresses": [{"city": "NYC"}, {"city": "LA"}]},
298
    {"name": "Jane", "addresses": [{"city": "SF"}]}
299
  ]
300
}
301
""";
302

303
JSONObject complex = JSON.parseObject(complexJson);
304

305
// Access nested arrays and objects
306
JSONArray users = complex.getJSONArray("users");
307
JSONObject firstUser = users.getJSONObject(0);
308
JSONArray addresses = firstUser.getJSONArray("addresses");
309
String firstCity = addresses.getJSONObject(0).getString("city"); // "NYC"
310

311
// Using JSONPath for complex access
312
String firstUserCity = (String) complex.getByPath("$.users[0].addresses[0].city"); // "NYC"
313

314
// Convert specific nested objects
315
User firstUserObj = firstUser.to(User.class);
316
List<Address> userAddresses = addresses.toJavaList(Address.class);
317
```
318

319
### Type Conversion Examples
320

321
```java
322
// JSONObject conversions
323
JSONObject obj = JSON.parseObject("{\"id\":1,\"name\":\"Product\",\"price\":99.99}");
324

325
// Safe type conversion with null handling
326
Integer id = obj.getInteger("id");           // 1
327
String name = obj.getString("name");         // "Product"  
328
Double price = obj.getDouble("price");       // 99.99
329
Integer missing = obj.getInteger("missing"); // null
330

331
// Convert entire object
332
Product product = obj.to(Product.class);
333

334
// JSONArray conversions
335
JSONArray numbers = JSON.parseArray("[1,2,3,4,5]");
336
JSONArray mixed = JSON.parseArray("[\"hello\",42,true,null]");
337

338
String first = mixed.getString(0);    // "hello"
339
Integer second = mixed.getInteger(1); // 42
340
Boolean third = mixed.getBoolean(2);  // true
341
Object fourth = mixed.get(3);         // null
342

343
// Convert to standard Java collections
344
List<Integer> numberList = numbers.toJavaList(Integer.class);
345
Object[] mixedArray = mixed.toArray();
346
```