0
# Gson
1

2
Gson is a Java library that can be used to convert Java Objects into their JSON representation. It can also be used to convert a JSON string to an equivalent Java object. Gson can work with arbitrary Java objects including pre-existing objects that you do not have source-code access to.
3

4
## Package Information
5

6
- **Package Name**: com.google.code.gson:gson
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>com.google.code.gson</groupId>
13
    <artifactId>gson</artifactId>
14
    <version>2.13.1</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.google.gson.Gson;
22
import com.google.gson.GsonBuilder;
23
```
24

25
For JSON tree model:
26
```java
27
import com.google.gson.JsonElement;
28
import com.google.gson.JsonObject;
29
import com.google.gson.JsonArray;
30
import com.google.gson.JsonPrimitive;
31
```
32

33
For streaming:
34
```java
35
import com.google.gson.stream.JsonReader;
36
import com.google.gson.stream.JsonWriter;
37
```
38

39
## Basic Usage
40

41
```java
42
import com.google.gson.Gson;
43

44
// Simple object serialization
45
class Person {
46
    private String name;
47
    private int age;
48
    
49
    public Person(String name, int age) {
50
        this.name = name;
51
        this.age = age;
52
    }
53
}
54

55
// Create Gson instance
56
Gson gson = new Gson();
57

58
// Convert Java object to JSON
59
Person person = new Person("John", 30);
60
String json = gson.toJson(person);
61
// Result: {"name":"John","age":30}
62

63
// Convert JSON to Java object
64
String jsonString = "{\"name\":\"Jane\",\"age\":25}";
65
Person deserializedPerson = gson.fromJson(jsonString, Person.class);
66
```
67

68
## Architecture
69

70
Gson is built around several key components:
71

72
- **Gson Class**: Main entry point providing `toJson()` and `fromJson()` methods
73
- **GsonBuilder**: Builder pattern for configuring Gson instances with custom settings
74
- **JSON Tree Model**: Object representation (JsonElement hierarchy) for manipulating JSON as trees
75
- **Streaming API**: Memory-efficient reading/writing for large JSON documents
76
- **Type Adapters**: Pluggable serialization/deserialization for custom types
77
- **Reflection System**: Automatic object mapping using Java reflection
78

79
## Capabilities
80

81
### Object Serialization and Deserialization
82

83
Core functionality for converting between Java objects and JSON strings. Handles arbitrarily complex objects with deep inheritance hierarchies and generic types.
84

85
```java { .api }
86
public String toJson(Object src);
87
public String toJson(Object src, Type typeOfSrc);
88
public <T> T fromJson(String json, Class<T> classOfT);
89
public <T> T fromJson(String json, Type typeOfT);
90
public <T> T fromJson(String json, TypeToken<T> typeOfT);
91
```
92

93
[Object Serialization](./object-serialization.md)
94

95
### JSON Tree Model
96

97
Tree-based API for building and manipulating JSON structures programmatically. Useful when you need to modify JSON before serialization or after deserialization.
98

99
```java { .api }
100
public JsonElement toJsonTree(Object src);
101
public <T> T fromJson(JsonElement json, Class<T> classOfT);
102

103
abstract class JsonElement {
104
    public boolean isJsonObject();
105
    public boolean isJsonArray();
106
    public boolean isJsonPrimitive();
107
    public boolean isJsonNull();
108
}
109
```
110

111
[JSON Tree Model](./json-tree-model.md)
112

113
### Configuration and Customization
114

115
Extensive configuration options for controlling serialization behavior, field naming, date formatting, and custom type adapters.
116

117
```java { .api }
118
public final class GsonBuilder {
119
    public GsonBuilder setPrettyPrinting();
120
    public GsonBuilder serializeNulls();
121
    public GsonBuilder setFieldNamingPolicy(FieldNamingPolicy namingConvention);
122
    public GsonBuilder registerTypeAdapter(Type type, Object typeAdapter);
123
    public Gson create();
124
}
125
```
126

127
[Configuration](./configuration.md)
128

129
### Streaming API
130

131
Memory-efficient streaming API for processing large JSON documents without loading them entirely into memory.
132

133
```java { .api }
134
public class JsonReader implements Closeable {
135
    public JsonToken peek() throws IOException;
136
    public String nextString() throws IOException;
137
    public int nextInt() throws IOException;
138
    public void beginObject() throws IOException;
139
    public void endObject() throws IOException;
140
}
141

142
public class JsonWriter implements Closeable, Flushable {
143
    public JsonWriter name(String name) throws IOException;
144
    public JsonWriter value(String value) throws IOException;
145
    public JsonWriter beginObject() throws IOException;
146
    public JsonWriter endObject() throws IOException;
147
}
148
```
149

150
[Streaming API](./streaming-api.md)
151

152
### Type Adapters
153

154
Pluggable system for custom serialization and deserialization logic. Allows fine-grained control over how specific types are converted.
155

156
```java { .api }
157
public abstract class TypeAdapter<T> {
158
    public abstract void write(JsonWriter out, T value) throws IOException;
159
    public abstract T read(JsonReader in) throws IOException;
160
}
161

162
public interface TypeAdapterFactory {
163
    public <T> TypeAdapter<T> create(Gson gson, TypeToken<T> type);
164
}
165
```
166

167
[Type Adapters](./type-adapters.md)
168

169
### Annotations
170

171
Annotations for controlling serialization behavior on fields and classes without requiring configuration changes.
172

173
```java { .api }
174
@SerializedName("custom_name")
175
@Expose(serialize = true, deserialize = true)
176
@Since(1.0)
177
@Until(2.0)
178
@JsonAdapter(CustomAdapter.class)
179
```
180

181
[Annotations](./annotations.md)
182

183
## Types
184

185
```java { .api }
186
// Core exception types
187
class JsonParseException extends RuntimeException {}
188
class JsonSyntaxException extends JsonParseException {}
189
class JsonIOException extends JsonParseException {}
190

191
// Enums for configuration
192
enum FieldNamingPolicy {
193
    IDENTITY, UPPER_CAMEL_CASE, UPPER_CAMEL_CASE_WITH_SPACES,
194
    UPPER_CASE_WITH_UNDERSCORES, LOWER_CASE_WITH_UNDERSCORES,
195
    LOWER_CASE_WITH_DASHES, LOWER_CASE_WITH_DOTS
196
}
197

198
enum LongSerializationPolicy { DEFAULT, STRING }
199

200
enum ToNumberPolicy implements ToNumberStrategy {
201
    DOUBLE, LAZILY_PARSED_NUMBER, LONG_OR_DOUBLE, BIG_DECIMAL
202
}
203

204
// Type handling
205
class TypeToken<T> {
206
    public static <T> TypeToken<T> get(Class<T> type);
207
    public static TypeToken<?> get(Type type);
208
    public Type getType();
209
}
210
```