0
# Selenium JSON
1

2
Selenium JSON is a comprehensive JSON processing library that serves as the core JSON handling component within the Selenium WebDriver ecosystem. It provides robust serialization and deserialization capabilities for converting between Java objects and JSON representations, supporting standard Java types, custom objects, and complex nested data structures with type coercion mechanisms and streaming processing.
3

4
## Package Information
5

6
- **Package Name**: selenium-json
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Maven Coordinates**: `org.seleniumhq.selenium:selenium-json:4.33.0`
10
- **Installation**: Add to Maven dependencies or include in Bazel BUILD file
11

12
## Core Imports
13

14
```java
15
import org.openqa.selenium.json.Json;
16
import org.openqa.selenium.json.JsonInput;
17
import org.openqa.selenium.json.JsonOutput;
18
```
19

20
For type-safe deserialization:
21

22
```java
23
import org.openqa.selenium.json.TypeToken;
24
import org.openqa.selenium.json.PropertySetting;
25
```
26

27
## Basic Usage
28

29
```java
30
import org.openqa.selenium.json.Json;
31
import java.util.Map;
32
import java.util.List;
33

34
// Create JSON processor instance
35
Json json = new Json();
36

37
// Serialize objects to JSON
38
String jsonString = json.toJson(myObject);
39

40
// Deserialize JSON to specific types
41
MyClass obj = json.toType(jsonString, MyClass.class);
42

43
// Work with generic types using TypeToken
44
List<Map<String, Object>> data = json.toType(
45
    jsonString, 
46
    new TypeToken<List<Map<String, Object>>>() {}.getType()
47
);
48

49
// Control property setting during deserialization
50
MyClass obj = json.toType(jsonString, MyClass.class, PropertySetting.BY_FIELD);
51
```
52

53
## Architecture
54

55
Selenium JSON is built around several key components:
56

57
- **Json Class**: Main entry point providing high-level serialization/deserialization methods
58
- **Streaming Processors**: `JsonInput` and `JsonOutput` for memory-efficient, streaming JSON processing
59
- **Type Coercion System**: Extensible framework for converting between JSON and Java types
60
- **Property Setting Strategies**: Configurable approaches for setting object properties during deserialization
61
- **Built-in Type Support**: Comprehensive support for Java primitives, collections, and common types
62

63
The library supports multiple serialization patterns including JavaBean conventions, static `fromJson`/`toJson` methods, and custom `TypeCoercer` implementations for maximum flexibility.
64

65
## Capabilities
66

67
### Core JSON Processing
68

69
High-level JSON serialization and deserialization operations using the main `Json` class. Provides simple string-based and reader-based processing with configurable depth limits and property setting strategies.
70

71
```java { .api }
72
public class Json {
73
    public String toJson(Object toConvert);
74
    public String toJson(Object toConvert, int maxDepth);
75
    public <T> T toType(String source, Type typeOfT);
76
    public <T> T toType(String source, Type typeOfT, PropertySetting setter);
77
    public <T> T toType(Reader source, Type typeOfT);
78
    public <T> T toType(Reader source, Type typeOfT, PropertySetting setter);
79
    public JsonInput newInput(Reader from) throws UncheckedIOException;
80
    public JsonOutput newOutput(Appendable to) throws UncheckedIOException;
81
}
82
```
83

84
[Core Processing](./core-processing.md)
85

86
### Streaming JSON Input
87

88
Advanced JSON reading and deserialization using `JsonInput` for memory-efficient processing of large JSON documents. Supports custom type coercers, streaming parsing, and fine-grained control over the parsing process.
89

90
```java { .api }
91
public class JsonInput implements Closeable {
92
    public PropertySetting propertySetting(PropertySetting setter);
93
    public JsonInput addCoercers(TypeCoercer<?>... coercers);
94
    public JsonInput addCoercers(Iterable<TypeCoercer<?>> coercers);
95
    public JsonType peek();
96
    public boolean nextBoolean();
97
    public String nextName();
98
    public Object nextNull();
99
    public Number nextNumber();
100
    public String nextString();
101
    public Instant nextInstant();
102
    public <T> T read(Type type);
103
    public <T> List<T> readArray(Type type);
104
}
105
```
106

107
[Streaming Input](./streaming-input.md)
108

109
### Streaming JSON Output
110

111
Advanced JSON writing and serialization using `JsonOutput` for memory-efficient generation of JSON documents. Supports pretty printing, depth control, and fine-grained control over the serialization process.
112

113
```java { .api }
114
public class JsonOutput implements Closeable {
115
    public JsonOutput setPrettyPrint(boolean enablePrettyPrinting);
116
    public JsonOutput writeClassName(boolean writeClassName);
117
    public JsonOutput beginObject();
118
    public JsonOutput name(String name);
119
    public JsonOutput endObject();
120
    public JsonOutput beginArray();
121
    public JsonOutput endArray();
122
    public JsonOutput write(Object value);
123
    public JsonOutput write(Object value, int maxDepth);
124
}
125
```
126

127
[Streaming Output](./streaming-output.md)
128

129
### Type System and Coercion
130

131
Comprehensive type conversion system supporting custom type coercers, generic type handling with `TypeToken`, and extensible type conversion patterns for complex object hierarchies.
132

133
```java { .api }
134
public abstract class TypeToken<T> {
135
    public Type getType();
136
}
137

138
public abstract class TypeCoercer<T> implements Predicate<Class<?>>, Function<Type, BiFunction<JsonInput, PropertySetting, T>> {
139
    public abstract boolean test(Class<?> aClass);
140
    public abstract BiFunction<JsonInput, PropertySetting, T> apply(Type type);
141
}
142

143
public enum PropertySetting {
144
    BY_NAME,
145
    BY_FIELD
146
}
147
```
148

149
[Type System](./type-system.md)
150

151
## Constants and Utilities
152

153
```java { .api }
154
// Content type constant
155
public static final String JSON_UTF_8 = "application/json; charset=utf-8";
156

157
// Common type tokens
158
public static final Type LIST_OF_MAPS_TYPE = new TypeToken<List<Map<String, Object>>>() {}.getType();
159
public static final Type MAP_TYPE = new TypeToken<Map<String, Object>>() {}.getType();
160
public static final Type OBJECT_TYPE = new TypeToken<Object>() {}.getType();
161

162
// Maximum traversal depth
163
public static final int MAX_DEPTH = 100;
164
```
165

166
## Exception Handling
167

168
```java { .api }
169
public class JsonException extends WebDriverException {
170
    public JsonException(String message);
171
    public JsonException(Throwable cause);
172
    public JsonException(String message, Throwable cause);
173
}
174
```
175

176
## Supported Types
177

178
**Standard Java Types (Built-in Processing):**
179
- Primitives: `Boolean`, `Byte`, `Double`, `Float`, `Integer`, `Long`, `Short`
180
- Collections: `List`, `Set`, Arrays
181
- Standard Types: `Map`, `String`, `Enum`, `URI`, `URL`, `UUID`, `Instant`, `Date`, `File`
182

183
**Custom Object Support:**
184
- Objects with `fromJson(T)` static methods
185
- Objects with `fromJson(JsonInput)` static methods  
186
- Objects with `toJson()` methods
187
- Objects with `asMap()` or `toMap()` methods
188
- JavaBean-compliant objects with getter/setter methods