0
# Core JSON Processing
1

2
High-level JSON serialization and deserialization operations using the main `Json` class. This provides the simplest interface for converting between Java objects and JSON strings or readers, with built-in type coercion and configurable processing options.
3

4
## Capabilities
5

6
### Json Class
7

8
The main entry point for JSON processing operations, providing both serialization and deserialization methods with sensible defaults.
9

10
```java { .api }
11
/**
12
 * The Json class is the entrypoint for the JSON processing features of the Selenium API.
13
 * Supports built-in JSON processing for standard types and facilities for custom data types.
14
 */
15
public class Json {
16
    
17
    // Serialization methods
18
    
19
    /**
20
     * Serialize the specified object to JSON string representation.
21
     * Uses the default maximum depth limit.
22
     * 
23
     * @param toConvert the object to be serialized
24
     * @return JSON string representing the specified object
25
     */
26
    public String toJson(Object toConvert);
27
    
28
    /**
29
     * Serialize the specified object to JSON string representation.
30
     * 
31
     * @param toConvert the object to be serialized
32
     * @param maxDepth maximum depth of nested object traversal
33
     * @return JSON string representing the specified object
34
     * @throws JsonException if an I/O exception is encountered
35
     */
36
    public String toJson(Object toConvert, int maxDepth);
37
    
38
    // Deserialization methods with String input
39
    
40
    /**
41
     * Deserialize the specified JSON string into an object of the specified type.
42
     * Uses the BY_NAME strategy to assign values to properties.
43
     * 
44
     * @param source serialized source as JSON string
45
     * @param typeOfT data type for deserialization (class or TypeToken)
46
     * @return object of the specified type deserialized from source
47
     * @param <T> result type (as specified by typeOfT)
48
     * @throws JsonException if an I/O exception is encountered
49
     */
50
    public <T> T toType(String source, Type typeOfT);
51
    
52
    /**
53
     * Deserialize the specified JSON string into an object of the specified type.
54
     * 
55
     * @param source serialized source as JSON string
56
     * @param typeOfT data type for deserialization (class or TypeToken)
57
     * @param setter strategy used to assign values during deserialization
58
     * @return object of the specified type deserialized from source
59
     * @param <T> result type (as specified by typeOfT)
60
     * @throws JsonException if an I/O exception is encountered
61
     */
62
    public <T> T toType(String source, Type typeOfT, PropertySetting setter);
63
    
64
    // Deserialization methods with Reader input
65
    
66
    /**
67
     * Deserialize the JSON string supplied by the specified Reader into an object of the specified type.
68
     * Uses the BY_NAME strategy to assign values to properties.
69
     * 
70
     * @param source Reader that supplies a serialized JSON string
71
     * @param typeOfT data type for deserialization (class or TypeToken)
72
     * @return object of the specified type deserialized from source
73
     * @param <T> result type (as specified by typeOfT)
74
     * @throws JsonException if an I/O exception is encountered
75
     */
76
    public <T> T toType(Reader source, Type typeOfT);
77
    
78
    /**
79
     * Deserialize the JSON string supplied by the specified Reader into an object of the specified type.
80
     * 
81
     * @param source Reader that supplies a serialized JSON string
82
     * @param typeOfT data type for deserialization (class or TypeToken)
83
     * @param setter strategy used to assign values during deserialization
84
     * @return object of the specified type deserialized from source
85
     * @param <T> result type (as specified by typeOfT)
86
     * @throws JsonException if an I/O exception is encountered
87
     */
88
    public <T> T toType(Reader source, Type typeOfT, PropertySetting setter);
89
    
90
    // Factory methods for streaming processors
91
    
92
    /**
93
     * Create a new JsonInput object to traverse the JSON string supplied by the specified Reader.
94
     * Uses the BY_NAME strategy to assign values to properties in deserialized objects.
95
     * 
96
     * @param from Reader that supplies a serialized JSON string
97
     * @return JsonInput object to traverse the JSON string supplied by from
98
     * @throws UncheckedIOException if an I/O exception occurs
99
     */
100
    public JsonInput newInput(Reader from) throws UncheckedIOException;
101
    
102
    /**
103
     * Create a new JsonOutput object to produce a serialized JSON string in the specified Appendable.
104
     * 
105
     * @param to Appendable that consumes a serialized JSON string
106
     * @return JsonOutput object to produce a JSON string in to
107
     * @throws UncheckedIOException if an I/O exception occurs
108
     */
109
    public JsonOutput newOutput(Appendable to) throws UncheckedIOException;
110
}
111
```
112

113
### Constants
114

115
Pre-defined constants for common use cases and content types.
116

117
```java { .api }
118
/**
119
 * The value of Content-Type headers for HTTP requests and responses with JSON entities
120
 */
121
public static final String JSON_UTF_8 = "application/json; charset=utf-8";
122

123
/**
124
 * Specifier for List<Map<String, Object>> input/output type
125
 */
126
public static final Type LIST_OF_MAPS_TYPE = new TypeToken<List<Map<String, Object>>>() {}.getType();
127

128
/**
129
 * Specifier for Map<String, Object> input/output type
130
 */
131
public static final Type MAP_TYPE = new TypeToken<Map<String, Object>>() {}.getType();
132

133
/**
134
 * Specifier for Object input/output type
135
 */
136
public static final Type OBJECT_TYPE = new TypeToken<Object>() {}.getType();
137
```
138

139
## Usage Examples
140

141
### Basic Serialization
142

143
```java
144
import org.openqa.selenium.json.Json;
145

146
Json json = new Json();
147

148
// Serialize simple objects
149
String result = json.toJson("Hello World");
150
// Result: "\"Hello World\""
151

152
String result = json.toJson(42);
153
// Result: "42"
154

155
String result = json.toJson(Arrays.asList(1, 2, 3));
156
// Result: "[1,2,3]"
157

158
// Serialize with depth limit
159
String result = json.toJson(complexNestedObject, 5);
160
```
161

162
### Basic Deserialization
163

164
```java
165
import org.openqa.selenium.json.Json;
166
import org.openqa.selenium.json.TypeToken;
167

168
Json json = new Json();
169

170
// Deserialize to simple types
171
String text = json.toType("\"Hello World\"", String.class);
172
Integer number = json.toType("42", Integer.class);
173

174
// Deserialize to generic collections using TypeToken
175
List<Integer> numbers = json.toType(
176
    "[1,2,3]", 
177
    new TypeToken<List<Integer>>() {}.getType()
178
);
179

180
// Deserialize to Map using predefined type constant
181
Map<String, Object> data = json.toType(
182
    "{\"name\":\"John\",\"age\":30}", 
183
    Json.MAP_TYPE
184
);
185
```
186

187
### Custom Objects
188

189
```java
190
// Object with fromJson static method
191
public class Person {
192
    private String name;
193
    private int age;
194
    
195
    public static Person fromJson(Map<String, Object> data) {
196
        Person person = new Person();
197
        person.name = (String) data.get("name");
198
        person.age = ((Number) data.get("age")).intValue();
199
        return person;
200
    }
201
    
202
    public Map<String, Object> toJson() {
203
        Map<String, Object> result = new HashMap<>();
204
        result.put("name", name);
205
        result.put("age", age);
206
        return result;
207
    }
208
}
209

210
// Usage
211
Json json = new Json();
212
Person person = new Person("John", 30);
213
String jsonString = json.toJson(person);
214
Person restored = json.toType(jsonString, Person.class);
215
```
216

217
### JavaBean Objects
218

219
```java
220
// JavaBean-compliant class
221
public class Product {
222
    private String name;
223
    private double price;
224
    
225
    public String getName() { return name; }
226
    public void setName(String name) { this.name = name; }
227
    
228
    public double getPrice() { return price; }
229
    public void setPrice(double price) { this.price = price; }
230
}
231

232
// Usage
233
Json json = new Json();
234
Product product = new Product();
235
product.setName("Laptop");
236
product.setPrice(999.99);
237

238
String jsonString = json.toJson(product);
239
Product restored = json.toType(jsonString, Product.class);
240

241
// Use BY_FIELD strategy to set fields directly
242
Product restored = json.toType(jsonString, Product.class, PropertySetting.BY_FIELD);
243
```
244

245
### Working with Readers
246

247
```java
248
import java.io.StringReader;
249
import java.io.FileReader;
250

251
Json json = new Json();
252

253
// From StringReader
254
try (StringReader reader = new StringReader("{\"name\":\"John\"}")) {
255
    Person person = json.toType(reader, Person.class);
256
}
257

258
// From FileReader
259
try (FileReader reader = new FileReader("data.json")) {
260
    List<Person> people = json.toType(
261
        reader, 
262
        new TypeToken<List<Person>>() {}.getType()
263
    );
264
}
265
```