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
```