0
# Google HTTP Client GSON
1

2
Google HTTP Client GSON is a low-level JSON library implementation based on Google's GSON library for the Google HTTP Client Library for Java ecosystem. It provides a pluggable JSON processing component that enables efficient parsing and serialization of HTTP response and request content using GSON as the underlying JSON library.
3

4
## Package Information
5

6
- **Package Name**: google-http-client-gson
7
- **Package Type**: maven
8
- **Group ID**: com.google.http-client
9
- **Artifact ID**: google-http-client-gson
10
- **Language**: Java
11
- **Installation**: 
12
  ```xml
13
  <dependency>
14
    <groupId>com.google.http-client</groupId>
15
    <artifactId>google-http-client-gson</artifactId>
16
    <version>2.0.0</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java
23
import com.google.api.client.json.gson.GsonFactory;
24
import com.google.api.client.json.JsonParser;
25
import com.google.api.client.json.JsonGenerator;
26
import com.google.api.client.json.JsonObjectParser;
27
```
28

29
## Basic Usage
30

31
```java
32
import com.google.api.client.json.gson.GsonFactory;
33
import com.google.api.client.json.JsonParser;
34
import com.google.api.client.json.JsonGenerator;
35
import java.io.StringWriter;
36
import java.io.IOException;
37

38
public class Example {
39
  public static void main(String[] args) throws IOException {
40
    // Create a factory instance (recommended: use default instance)  
41
    GsonFactory jsonFactory = GsonFactory.getDefaultInstance();
42
    
43
    // Parse JSON from string
44
    String jsonString = "{\"name\":\"John\",\"age\":30}";
45
    JsonParser parser = jsonFactory.createJsonParser(jsonString);
46
    
47
    // Generate JSON to string
48
    StringWriter writer = new StringWriter();
49
    JsonGenerator generator = jsonFactory.createJsonGenerator(writer);
50
    generator.writeStartObject();
51
    generator.writeFieldName("name");
52
    generator.writeString("John");
53
    generator.writeFieldName("age");
54
    generator.writeNumber(30);
55
    generator.writeEndObject();
56
    generator.close();
57
    String result = writer.toString();
58
    
59
    // High-level operations for object serialization/deserialization
60
    MyObject obj = new MyObject("John", 30);
61
    String json = jsonFactory.toString(obj);
62
    MyObject parsed = jsonFactory.fromString(json, MyObject.class);
63
  }
64
}
65

66
class MyObject {
67
  public String name;
68
  public int age;
69
  
70
  public MyObject(String name, int age) {
71
    this.name = name;
72
    this.age = age;
73
  }
74
}
75
```
76

77
## Architecture
78

79
Google HTTP Client GSON is built around several key components:
80

81
- **Factory Pattern**: `GsonFactory` serves as the central factory for creating JSON parsers and generators, following the Abstract Factory pattern implemented by the parent `JsonFactory` class
82
- **GSON Integration**: Uses Google's GSON library internally for actual JSON processing while providing the Google HTTP Client Library's standardized API surface
83
- **Inheritance Hierarchy**: Extends `JsonFactory` and provides concrete implementations of abstract methods while inheriting high-level convenience methods
84
- **Thread Safety Model**: Factory instances are thread-safe and can be shared, while individual parsers and generators are not thread-safe
85
- **Pluggable Design**: Implements the JsonFactory interface, making it a drop-in replacement for other JSON implementations within the Google HTTP Client framework
86

87
## Capabilities
88

89
### Factory Management
90

91
Create and configure GsonFactory instances for JSON processing operations.
92

93
```java { .api }
94
@Beta
95
public static GsonFactory getDefaultInstance()
96
public static GsonFactory.Builder builder()
97
public GsonFactory()
98
```
99

100
**getDefaultInstance()**: Returns a global thread-safe singleton instance. This is the recommended approach for most applications. Note: This method is marked with @Beta annotation indicating it may change in future versions.
101

102
**builder()**: Returns a Builder instance for creating customized GsonFactory instances with specific configurations.
103

104
**GsonFactory()**: Default constructor for creating new instances. Users should prefer getDefaultInstance() or builder().
105

106
### JSON Parser Creation
107

108
Create JsonParser instances from various input sources for reading JSON data.
109

110
```java { .api }
111
public JsonParser createJsonParser(InputStream in) throws IOException
112
public JsonParser createJsonParser(InputStream in, Charset charset) throws IOException
113
public JsonParser createJsonParser(String value) throws IOException
114
public JsonParser createJsonParser(Reader reader) throws IOException
115
```
116

117
**createJsonParser(InputStream in)**: Creates a parser from InputStream using UTF-8 encoding by default.
118

119
**createJsonParser(InputStream in, Charset charset)**: Creates a parser from InputStream with specified character encoding.
120

121
**createJsonParser(String value)**: Creates a parser directly from a JSON string.
122

123
**createJsonParser(Reader reader)**: Creates a parser from a Reader object.
124

125
### JSON Generator Creation
126

127
Create JsonGenerator instances for various output destinations for writing JSON data.
128

129
```java { .api }
130
public JsonGenerator createJsonGenerator(OutputStream out, Charset enc) throws IOException
131
public JsonGenerator createJsonGenerator(Writer writer) throws IOException
132
```
133

134
**createJsonGenerator(OutputStream out, Charset enc)**: Creates a generator that writes to OutputStream with specified character encoding.
135

136
**createJsonGenerator(Writer writer)**: Creates a generator that writes to a Writer object.
137

138
### Configuration Builder
139

140
Configure GsonFactory instances with custom settings using the Builder pattern.
141

142
```java { .api }
143
public static final class GsonFactory.Builder {
144
  public GsonFactory.Builder setReadLeniency(boolean readLeniency)
145
  public GsonFactory build()
146
}
147
```
148

149
**setReadLeniency(boolean readLeniency)**: Configures JSON parser leniency. When true, the parser is more permissive with malformed JSON. Default is false. Returns the Builder for method chaining.
150

151
**build()**: Creates and returns a configured GsonFactory instance.
152

153
### High-Level JSON Operations
154

155
Inherited from JsonFactory, these methods provide convenient high-level operations for common JSON tasks.
156

157
```java { .api }
158
public final String toString(Object item) throws IOException
159
public final String toPrettyString(Object item) throws IOException
160
public final byte[] toByteArray(Object item) throws IOException
161
public final <T> T fromString(String value, Class<T> destinationClass) throws IOException
162
public final <T> T fromInputStream(InputStream inputStream, Class<T> destinationClass) throws IOException
163
public final <T> T fromInputStream(InputStream inputStream, Charset charset, Class<T> destinationClass) throws IOException
164
public final <T> T fromReader(Reader reader, Class<T> destinationClass) throws IOException
165
public final JsonObjectParser createJsonObjectParser() throws IOException
166
```
167

168
**toString(Object item)**: Serializes an object to a JSON string.
169

170
**toPrettyString(Object item)**: Serializes an object to a pretty-printed JSON string with formatting.
171

172
**toByteArray(Object item)**: Serializes an object to a JSON byte array using UTF-8 encoding.
173

174
**fromString(String value, Class<T> destinationClass)**: Parses JSON string into an object of the specified class.
175

176
**fromInputStream(InputStream inputStream, Class<T> destinationClass)**: Parses JSON from InputStream into an object of the specified class using UTF-8 encoding.
177

178
**fromInputStream(InputStream inputStream, Charset charset, Class<T> destinationClass)**: Parses JSON from InputStream with specified charset into an object of the specified class.
179

180
**fromReader(Reader reader, Class<T> destinationClass)**: Parses JSON from Reader into an object of the specified class.
181

182
**createJsonObjectParser()**: Creates a JsonObjectParser instance for parsing JSON into generic objects.
183

184
## Types
185

186
```java { .api }
187
public class GsonFactory extends JsonFactory {
188
  // Implementation details handled by parent class JsonFactory
189
}
190

191
public static final class GsonFactory.Builder {
192
  // Builder pattern for GsonFactory configuration
193
}
194
```
195

196
## Thread Safety
197

198
- **GsonFactory**: Thread-safe. A single instance can be shared across multiple threads.
199
- **JsonParser**: Not thread-safe. Each parsing operation should use its own parser instance.
200
- **JsonGenerator**: Not thread-safe. Each generation operation should use its own generator instance.
201

202
## Error Handling
203

204
The library integrates with the Google HTTP Client Library error handling patterns. Most JSON operations declare `IOException`:
205

206
- **Parser/Generator Creation Methods**: All `createJsonParser()` and `createJsonGenerator()` methods declare `throws IOException`
207
- **High-Level Operations**: All serialization (`toString`, `toPrettyString`, `toByteArray`) and deserialization (`fromString`, `fromInputStream`, `fromReader`) methods declare `throws IOException`
208
- **Parser/Generator Operations**: Individual parser and generator operations can throw `IOException` for I/O errors
209
- **Configuration Methods**: Builder methods do not throw checked exceptions
210
- **Static Methods**: `getDefaultInstance()` and `builder()` do not throw checked exceptions
211

212
Standard Java runtime exceptions may also occur for invalid input or configuration errors.
213

214
## Integration Notes
215

216
This library is designed to integrate seamlessly with the Google HTTP Client Library ecosystem. It implements the JsonFactory interface, making it a drop-in replacement for other JSON implementations within the Google HTTP Client framework. The library uses GSON internally for actual JSON processing while providing the Google HTTP Client Library's standardized API surface.