0
# Object Serialization
1

2
The core functionality of Gson for converting between Java objects and JSON strings.
3

4
## Serialization (Java to JSON)
5

6
### Basic Serialization
7

8
```java { .api }
9
public String toJson(Object src);
10
```
11

12
Converts any Java object to its JSON string representation using default settings.
13

14
**Usage:**
15
```java
16
Gson gson = new Gson();
17
Person person = new Person("Alice", 30);
18
String json = gson.toJson(person);
19
// Result: {"name":"Alice","age":30}
20
```
21

22
### Serialization with Type Information
23

24
```java { .api }
25
public String toJson(Object src, Type typeOfSrc);
26
```
27

28
Explicitly specifies the type for serialization, useful for generic collections and inheritance hierarchies.
29

30
**Usage:**
31
```java
32
List<String> names = Arrays.asList("Alice", "Bob", "Charlie");
33
Type listType = new TypeToken<List<String>>(){}.getType();
34
String json = gson.toJson(names, listType);
35
// Result: ["Alice","Bob","Charlie"]
36
```
37

38
### Serialization to Writer
39

40
```java { .api }
41
public void toJson(Object src, Appendable writer) throws JsonIOException;
42
public void toJson(Object src, Type typeOfSrc, Appendable writer) throws JsonIOException;
43
public void toJson(Object src, Type typeOfSrc, JsonWriter writer) throws JsonIOException;
44
```
45

46
Serialize directly to a Writer or JsonWriter for memory efficiency or streaming output.
47

48
**Usage:**
49
```java
50
StringWriter writer = new StringWriter();
51
gson.toJson(person, writer);
52
String json = writer.toString();
53
```
54

55
## Deserialization (JSON to Java)
56

57
### Basic Deserialization
58

59
```java { .api }
60
public <T> T fromJson(String json, Class<T> classOfT) throws JsonSyntaxException;
61
```
62

63
Converts JSON string to Java object of the specified class.
64

65
**Usage:**
66
```java
67
String json = "{\"name\":\"Bob\",\"age\":25}";
68
Person person = gson.fromJson(json, Person.class);
69
```
70

71
### Deserialization with Generic Types
72

73
```java { .api }
74
public <T> T fromJson(String json, Type typeOfT) throws JsonSyntaxException;
75
public <T> T fromJson(String json, TypeToken<T> typeOfT) throws JsonSyntaxException;
76
```
77

78
Handles generic types like collections and maps using Type or TypeToken.
79

80
**Usage:**
81
```java
82
String json = "[\"Alice\",\"Bob\",\"Charlie\"]";
83
Type listType = new TypeToken<List<String>>(){}.getType();
84
List<String> names = gson.fromJson(json, listType);
85

86
// Or using TypeToken directly
87
TypeToken<List<String>> token = new TypeToken<List<String>>(){};
88
List<String> names = gson.fromJson(json, token);
89
```
90

91
### Deserialization from Reader
92

93
```java { .api }
94
public <T> T fromJson(Reader json, Class<T> classOfT) throws JsonIOException, JsonSyntaxException;
95
public <T> T fromJson(Reader json, Type typeOfT) throws JsonIOException, JsonSyntaxException;
96
public <T> T fromJson(Reader json, TypeToken<T> typeOfT) throws JsonIOException, JsonSyntaxException;
97
```
98

99
Deserialize from a Reader for memory-efficient processing of large files.
100

101
**Usage:**
102
```java
103
FileReader reader = new FileReader("data.json");
104
Person person = gson.fromJson(reader, Person.class);
105
reader.close();
106
```
107

108
### Deserialization from JsonReader
109

110
```java { .api }
111
public <T> T fromJson(JsonReader reader, Type typeOfT) throws JsonIOException, JsonSyntaxException;
112
public <T> T fromJson(JsonReader reader, TypeToken<T> typeOfT) throws JsonIOException, JsonSyntaxException;
113
```
114

115
Deserialize from JsonReader for streaming API integration.
116

117
**Usage:**
118
```java
119
JsonReader reader = new JsonReader(new StringReader(json));
120
Person person = gson.fromJson(reader, Person.class);
121
reader.close();
122
```
123

124
## Complex Object Handling
125

126
### Collections
127

128
Gson automatically handles standard Java collections:
129

130
```java
131
// Lists
132
List<String> list = Arrays.asList("a", "b", "c");
133
String json = gson.toJson(list);
134
List<String> restored = gson.fromJson(json, new TypeToken<List<String>>(){}.getType());
135

136
// Maps
137
Map<String, Integer> map = new HashMap<>();
138
map.put("one", 1);
139
map.put("two", 2);
140
String json = gson.toJson(map);
141
Map<String, Integer> restored = gson.fromJson(json, new TypeToken<Map<String, Integer>>(){}.getType());
142
```
143

144
### Arrays
145

146
```java
147
int[] numbers = {1, 2, 3, 4, 5};
148
String json = gson.toJson(numbers);
149
int[] restored = gson.fromJson(json, int[].class);
150
```
151

152
### Nested Objects
153

154
```java
155
class Address {
156
    String street;
157
    String city;
158
}
159

160
class Person {
161
    String name;
162
    Address address;
163
}
164

165
Person person = new Person();
166
person.name = "John";
167
person.address = new Address();
168
person.address.street = "123 Main St";
169
person.address.city = "Springfield";
170

171
String json = gson.toJson(person);
172
Person restored = gson.fromJson(json, Person.class);
173
```
174

175
### Inheritance
176

177
```java
178
class Animal {
179
    String name;
180
}
181

182
class Dog extends Animal {
183
    String breed;
184
}
185

186
Dog dog = new Dog();
187
dog.name = "Buddy";
188
dog.breed = "Golden Retriever";
189

190
// Serialize as Dog type
191
String json = gson.toJson(dog, Dog.class);
192
Dog restored = gson.fromJson(json, Dog.class);
193
```
194

195
## Error Handling
196

197
```java { .api }
198
class JsonSyntaxException extends JsonParseException {
199
    // Thrown when JSON syntax is invalid
200
}
201

202
class JsonIOException extends JsonParseException {
203
    // Thrown when I/O errors occur during reading/writing
204
}
205
```
206

207
**Usage:**
208
```java
209
try {
210
    Person person = gson.fromJson(invalidJson, Person.class);
211
} catch (JsonSyntaxException e) {
212
    System.err.println("Invalid JSON syntax: " + e.getMessage());
213
} catch (JsonIOException e) {
214
    System.err.println("I/O error: " + e.getMessage());
215
}
216
```