Google HTTP Client GSON

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.

Package Information

• Package Name: google-http-client-gson
• Package Type: maven
• Group ID: com.google.http-client
• Artifact ID: google-http-client-gson
• Language: Java
• Installation:

  <dependency>
    <groupId>com.google.http-client</groupId>
    <artifactId>google-http-client-gson</artifactId>
    <version>2.0.0</version>
  </dependency>

Core Imports

import com.google.api.client.json.gson.GsonFactory;
import com.google.api.client.json.JsonParser;
import com.google.api.client.json.JsonGenerator;
import com.google.api.client.json.JsonObjectParser;

Basic Usage

import com.google.api.client.json.gson.GsonFactory;
import com.google.api.client.json.JsonParser;
import com.google.api.client.json.JsonGenerator;
import java.io.StringWriter;
import java.io.IOException;

public class Example {
  public static void main(String[] args) throws IOException {
    // Create a factory instance (recommended: use default instance)  
    GsonFactory jsonFactory = GsonFactory.getDefaultInstance();
    
    // Parse JSON from string
    String jsonString = "{\"name\":\"John\",\"age\":30}";
    JsonParser parser = jsonFactory.createJsonParser(jsonString);
    
    // Generate JSON to string
    StringWriter writer = new StringWriter();
    JsonGenerator generator = jsonFactory.createJsonGenerator(writer);
    generator.writeStartObject();
    generator.writeFieldName("name");
    generator.writeString("John");
    generator.writeFieldName("age");
    generator.writeNumber(30);
    generator.writeEndObject();
    generator.close();
    String result = writer.toString();
    
    // High-level operations for object serialization/deserialization
    MyObject obj = new MyObject("John", 30);
    String json = jsonFactory.toString(obj);
    MyObject parsed = jsonFactory.fromString(json, MyObject.class);
  }
}

class MyObject {
  public String name;
  public int age;
  
  public MyObject(String name, int age) {
    this.name = name;
    this.age = age;
  }
}

Architecture

Google HTTP Client GSON is built around several key components:

• 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
• GSON Integration: Uses Google's GSON library internally for actual JSON processing while providing the Google HTTP Client Library's standardized API surface
• Inheritance Hierarchy: Extends JsonFactory and provides concrete implementations of abstract methods while inheriting high-level convenience methods
• Thread Safety Model: Factory instances are thread-safe and can be shared, while individual parsers and generators are not thread-safe
• Pluggable Design: Implements the JsonFactory interface, making it a drop-in replacement for other JSON implementations within the Google HTTP Client framework

Capabilities

Factory Management

Create and configure GsonFactory instances for JSON processing operations.

@Beta
public static GsonFactory getDefaultInstance()
public static GsonFactory.Builder builder()
public GsonFactory()

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.

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

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

JSON Parser Creation

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

public JsonParser createJsonParser(InputStream in) throws IOException
public JsonParser createJsonParser(InputStream in, Charset charset) throws IOException
public JsonParser createJsonParser(String value) throws IOException
public JsonParser createJsonParser(Reader reader) throws IOException

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

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

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

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

JSON Generator Creation

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

public JsonGenerator createJsonGenerator(OutputStream out, Charset enc) throws IOException
public JsonGenerator createJsonGenerator(Writer writer) throws IOException

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

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

Configuration Builder

Configure GsonFactory instances with custom settings using the Builder pattern.

public static final class GsonFactory.Builder {
  public GsonFactory.Builder setReadLeniency(boolean readLeniency)
  public GsonFactory build()
}

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.

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

High-Level JSON Operations

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

public final String toString(Object item) throws IOException
public final String toPrettyString(Object item) throws IOException
public final byte[] toByteArray(Object item) throws IOException
public final <T> T fromString(String value, Class<T> destinationClass) throws IOException
public final <T> T fromInputStream(InputStream inputStream, Class<T> destinationClass) throws IOException
public final <T> T fromInputStream(InputStream inputStream, Charset charset, Class<T> destinationClass) throws IOException
public final <T> T fromReader(Reader reader, Class<T> destinationClass) throws IOException
public final JsonObjectParser createJsonObjectParser() throws IOException

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

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

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

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

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

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

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

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

Types

public class GsonFactory extends JsonFactory {
  // Implementation details handled by parent class JsonFactory
}

public static final class GsonFactory.Builder {
  // Builder pattern for GsonFactory configuration
}

Thread Safety

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

Error Handling

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

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

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

Integration Notes

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.