0
# JSON Object Operations
1

2
Create, modify, and query JSON objects with type-safe accessors, fluent interface support, and comprehensive member management capabilities.
3

4
## Capabilities
5

6
### Object Creation
7

8
Create JSON objects with constructors and static factory methods.
9

10
```java { .api }
11
/**
12
 * Creates an empty JSON object
13
 */
14
JsonObject();
15

16
/**
17
 * Creates a JSON object as a copy of another object
18
 * @param object the JSON object to copy
19
 */
20
JsonObject(JsonObject object);
21

22
/**
23
 * Creates an unmodifiable view of the given JSON object
24
 * @param object the JSON object to wrap
25
 * @return unmodifiable JSON object view
26
 */
27
static JsonObject unmodifiableObject(JsonObject object);
28
```
29

30
**Usage Examples:**
31

32
```java
33
import org.hjson.JsonObject;
34
import org.hjson.JsonValue;
35

36
// Create empty object
37
JsonObject emptyObj = new JsonObject();
38

39
// Create object with initial data
40
JsonObject person = new JsonObject()
41
    .add("name", "John Doe")
42
    .add("age", 30)
43
    .add("active", true);
44

45
// Copy constructor
46
JsonObject personCopy = new JsonObject(person);
47

48
// Unmodifiable view
49
JsonObject readOnlyPerson = JsonObject.unmodifiableObject(person);
50
```
51

52
### Adding Members (Fluent Interface)
53

54
Add new members to JSON objects with type-specific convenience methods.
55

56
```java { .api }
57
/**
58
 * Adds a new member with the specified name and JSON value
59
 * If a member with this name already exists, the new member is appended
60
 * @param name the name of the member to add
61
 * @param value the value of the member to add
62
 * @return the JSON object itself, to enable method chaining
63
 */
64
JsonObject add(String name, JsonValue value);
65

66
/**
67
 * Adds a new member with the specified name and string value
68
 * @param name the name of the member to add
69
 * @param value the string value of the member to add
70
 * @return the JSON object itself, to enable method chaining
71
 */
72
JsonObject add(String name, String value);
73

74
/**
75
 * Adds a new member with the specified name and int value
76
 * @param name the name of the member to add
77
 * @param value the int value of the member to add
78
 * @return the JSON object itself, to enable method chaining
79
 */
80
JsonObject add(String name, int value);
81

82
/**
83
 * Adds a new member with the specified name and long value
84
 * @param name the name of the member to add
85
 * @param value the long value of the member to add
86
 * @return the JSON object itself, to enable method chaining
87
 */
88
JsonObject add(String name, long value);
89

90
/**
91
 * Adds a new member with the specified name and float value
92
 * @param name the name of the member to add
93
 * @param value the float value of the member to add
94
 * @return the JSON object itself, to enable method chaining
95
 */
96
JsonObject add(String name, float value);
97

98
/**
99
 * Adds a new member with the specified name and double value
100
 * @param name the name of the member to add
101
 * @param value the double value of the member to add
102
 * @return the JSON object itself, to enable method chaining
103
 */
104
JsonObject add(String name, double value);
105

106
/**
107
 * Adds a new member with the specified name and boolean value
108
 * @param name the name of the member to add
109
 * @param value the boolean value of the member to add
110
 * @return the JSON object itself, to enable method chaining
111
 */
112
JsonObject add(String name, boolean value);
113
```
114

115
**Usage Examples:**
116

117
```java
118
import org.hjson.JsonObject;
119
import org.hjson.JsonArray;
120
import org.hjson.JsonValue;
121

122
// Fluent interface for building objects
123
JsonObject config = new JsonObject()
124
    .add("appName", "My Application")
125
    .add("version", "1.2.0")
126
    .add("port", 8080)
127
    .add("debugMode", false)
128
    .add("maxConnections", 1000L)
129
    .add("timeout", 30.5)
130
    .add("nullValue", JsonValue.NULL);
131

132
// Adding complex nested structures
133
JsonArray servers = new JsonArray()
134
    .add("server1.example.com")
135
    .add("server2.example.com");
136

137
JsonObject database = new JsonObject()
138
    .add("host", "localhost")
139
    .add("port", 5432)
140
    .add("name", "myapp_db");
141

142
config.add("servers", servers)
143
      .add("database", database);
144
```
145

146
### Setting/Replacing Members
147

148
Replace existing members or add new ones with set methods.
149

150
```java { .api }
151
/**
152
 * Sets the value of the member with the specified name to the specified JSON value
153
 * If the member does not exist, it is added. If it exists, its value is replaced
154
 * @param name the name of the member to set
155
 * @param value the value to set the member to
156
 * @return the JSON object itself, to enable method chaining
157
 */
158
JsonObject set(String name, JsonValue value);
159

160
/**
161
 * Sets the value of the member with the specified name to the specified string value
162
 * @param name the name of the member to set
163
 * @param value the string value to set the member to
164
 * @return the JSON object itself, to enable method chaining
165
 */
166
JsonObject set(String name, String value);
167

168
/**
169
 * Sets the value of the member with the specified name to the specified int value
170
 * @param name the name of the member to set
171
 * @param value the int value to set the member to
172
 * @return the JSON object itself, to enable method chaining
173
 */
174
JsonObject set(String name, int value);
175

176
/**
177
 * Sets the value of the member with the specified name to the specified long value
178
 * @param name the name of the member to set
179
 * @param value the long value to set the member to
180
 * @return the JSON object itself, to enable method chaining
181
 */
182
JsonObject set(String name, long value);
183

184
/**
185
 * Sets the value of the member with the specified name to the specified float value
186
 * @param name the name of the member to set
187
 * @param value the float value to set the member to
188
 * @return the JSON object itself, to enable method chaining
189
 */
190
JsonObject set(String name, float value);
191

192
/**
193
 * Sets the value of the member with the specified name to the specified double value
194
 * @param name the name of the member to set
195
 * @param value the double value to set the member to
196
 * @return the JSON object itself, to enable method chaining
197
 */
198
JsonObject set(String name, double value);
199

200
/**
201
 * Sets the value of the member with the specified name to the specified boolean value
202
 * @param name the name of the member to set
203
 * @param value the boolean value to set the member to
204
 * @return the JSON object itself, to enable method chaining
205
 */
206
JsonObject set(String name, boolean value);
207
```
208

209
**Usage Examples:**
210

211
```java
212
import org.hjson.JsonObject;
213

214
// Create object with initial values
215
JsonObject user = new JsonObject()
216
    .add("name", "John")
217
    .add("age", 25)
218
    .add("active", true);
219

220
// Update existing values
221
user.set("age", 26)           // Replace existing age
222
    .set("email", "john@example.com")  // Add new email field
223
    .set("active", false);    // Replace existing active status
224

225
// Conditional updates
226
if (someCondition) {
227
    user.set("lastLogin", System.currentTimeMillis());
228
}
229
```
230

231
### Accessing Members
232

233
Retrieve member values with type-safe accessors and default value support.
234

235
```java { .api }
236
/**
237
 * Returns the value of the member with the specified name
238
 * @param name the name of the member whose value is to be returned
239
 * @return the value of the member with the specified name, or null if not found
240
 */
241
JsonValue get(String name);
242

243
/**
244
 * Returns the string value of the member with the specified name
245
 * @param name the name of the member whose value is to be returned
246
 * @param defaultValue the value to be returned if the member is not found or not a string
247
 * @return the string value of the member, or the default value
248
 */
249
String getString(String name, String defaultValue);
250

251
/**
252
 * Returns the int value of the member with the specified name
253
 * @param name the name of the member whose value is to be returned
254
 * @param defaultValue the value to be returned if the member is not found or not a number
255
 * @return the int value of the member, or the default value
256
 */
257
int getInt(String name, int defaultValue);
258

259
/**
260
 * Returns the long value of the member with the specified name
261
 * @param name the name of the member whose value is to be returned
262
 * @param defaultValue the value to be returned if the member is not found or not a number
263
 * @return the long value of the member, or the default value
264
 */
265
long getLong(String name, long defaultValue);
266

267
/**
268
 * Returns the float value of the member with the specified name
269
 * @param name the name of the member whose value is to be returned
270
 * @param defaultValue the value to be returned if the member is not found or not a number
271
 * @return the float value of the member, or the default value
272
 */
273
float getFloat(String name, float defaultValue);
274

275
/**
276
 * Returns the double value of the member with the specified name
277
 * @param name the name of the member whose value is to be returned
278
 * @param defaultValue the value to be returned if the member is not found or not a number
279
 * @return the double value of the member, or the default value
280
 */
281
double getDouble(String name, double defaultValue);
282

283
/**
284
 * Returns the boolean value of the member with the specified name
285
 * @param name the name of the member whose value is to be returned
286
 * @param defaultValue the value to be returned if the member is not found or not a boolean
287
 * @return the boolean value of the member, or the default value
288
 */
289
boolean getBoolean(String name, boolean defaultValue);
290
```
291

292
**Usage Examples:**
293

294
```java
295
import org.hjson.JsonObject;
296
import org.hjson.JsonValue;
297
import org.hjson.JsonArray;
298

299
JsonObject config = JsonValue.readHjson("""
300
    {
301
        appName: "My App"
302
        port: 8080
303
        debugMode: true
304
        maxRetries: 3
305
        timeout: 30.5
306
        servers: ["server1", "server2"]
307
    }
308
    """).asObject();
309

310
// Safe access with defaults
311
String appName = config.getString("appName", "Unknown App");
312
int port = config.getInt("port", 3000);
313
boolean debug = config.getBoolean("debugMode", false);
314
double timeout = config.getDouble("timeout", 10.0);
315

316
// Access complex values
317
JsonValue serversValue = config.get("servers");
318
if (serversValue != null && serversValue.isArray()) {
319
    JsonArray servers = serversValue.asArray();
320
    System.out.println("Server count: " + servers.size());
321
}
322

323
// Handle missing values gracefully
324
String missingValue = config.getString("nonexistent", "default");
325
int missingNumber = config.getInt("nonexistent", -1);
326
```
327

328
### Member Management
329

330
Remove members and query object structure.
331

332
```java { .api }
333
/**
334
 * Removes the member with the specified name from this object
335
 * @param name the name of the member to remove
336
 * @return the JSON object itself, to enable method chaining
337
 */
338
JsonObject remove(String name);
339

340
/**
341
 * Returns the number of members in this object
342
 * @return the number of members
343
 */
344
int size();
345

346
/**
347
 * Returns true if this object contains no members
348
 * @return true if this object is empty
349
 */
350
boolean isEmpty();
351

352
/**
353
 * Returns a list of the names of all members in this object
354
 * The list is a copy and modifications do not affect the original object
355
 * @return list of member names
356
 */
357
List<String> names();
358
```
359

360
**Usage Examples:**
361

362
```java
363
import org.hjson.JsonObject;
364
import java.util.List;
365

366
JsonObject obj = new JsonObject()
367
    .add("name", "Test")
368
    .add("value", 42)
369
    .add("temp", "temporary");
370

371
// Query object structure
372
System.out.println("Size: " + obj.size()); // Output: Size: 3
373
System.out.println("Empty: " + obj.isEmpty()); // Output: Empty: false
374

375
// Get all member names
376
List<String> memberNames = obj.names();
377
System.out.println("Members: " + memberNames); // Output: Members: [name, value, temp]
378

379
// Remove temporary data
380
obj.remove("temp");
381
System.out.println("After removal: " + obj.size()); // Output: After removal: 2
382

383
// Check if empty after clearing
384
JsonObject empty = new JsonObject();
385
System.out.println("New object empty: " + empty.isEmpty()); // Output: New object empty: true
386
```
387

388
### Iteration
389

390
Iterate over object members with enhanced for-loop support.
391

392
```java { .api }
393
/**
394
 * Returns an iterator over the members in this object
395
 * @return iterator over Member objects
396
 */
397
Iterator<JsonObject.Member> iterator();
398

399
/**
400
 * Represents a member of a JSON object (name/value pair)
401
 */
402
static class Member {
403
    /**
404
     * Returns the name of this member
405
     * @return the member name
406
     */
407
    String getName();
408
    
409
    /**
410
     * Returns the value of this member
411
     * @return the member value
412
     */
413
    JsonValue getValue();
414
}
415
```
416

417
**Usage Examples:**
418

419
```java
420
import org.hjson.JsonObject;
421
import org.hjson.JsonObject.Member;
422

423
JsonObject person = new JsonObject()
424
    .add("firstName", "John")
425
    .add("lastName", "Doe")
426
    .add("age", 30)
427
    .add("active", true);
428

429
// Enhanced for-loop iteration
430
for (Member member : person) {
431
    String name = member.getName();
432
    JsonValue value = member.getValue();
433
    System.out.println(name + " = " + value);
434
}
435

436
// Iterator-based iteration
437
Iterator<Member> iterator = person.iterator();
438
while (iterator.hasNext()) {
439
    Member member = iterator.next();
440
    if (member.getValue().isString()) {
441
        System.out.println("String member: " + member.getName() + 
442
                          " = " + member.getValue().asString());
443
    }
444
}
445

446
// Process specific member types
447
for (Member member : person) {
448
    JsonValue value = member.getValue();
449
    if (value.isNumber()) {
450
        System.out.println("Number: " + member.getName() + " = " + value.asInt());
451
    } else if (value.isBoolean()) {
452
        System.out.println("Boolean: " + member.getName() + " = " + value.asBoolean());
453
    }
454
}
455
```
456

457
## Type Checking and Conversion
458

459
JsonObject inherits type checking and conversion methods from JsonValue:
460

461
```java { .api }
462
// Type checking (always returns true for JsonObject)
463
boolean isObject();
464
JsonType getType(); // Returns JsonType.OBJECT
465

466
// Safe conversion (returns this)
467
JsonObject asObject();
468

469
// Object equality and hashing
470
boolean equals(Object obj);
471
int hashCode();
472
```
473

474
## Thread Safety and Immutability
475

476
- **Thread Safety**: JsonObject is **not** thread-safe and requires external synchronization for concurrent access
477
- **Mutability**: JsonObject instances are mutable - methods like `add()`, `set()`, and `remove()` modify the object
478
- **Defensive Copying**: Use the copy constructor or `unmodifiableObject()` for safe sharing
479
- **Member Immutability**: Individual JsonValue members are immutable once added
480

481
## Best Practices
482

483
1. **Fluent Interface**: Chain method calls for readable object construction
484
2. **Default Values**: Always provide sensible defaults when accessing members
485
3. **Null Checking**: Check if `get()` returns null before using the value
486
4. **Type Safety**: Use type-specific getters (`getString()`, `getInt()`, etc.) instead of manual casting
487
5. **Unmodifiable Views**: Use `unmodifiableObject()` when passing objects to untrusted code
488
6. **Member Names**: Use consistent naming conventions for member names
489
7. **Error Handling**: Handle potential type conversion errors gracefully