0
# Retrofit Moshi Converter
1

2
A Retrofit converter factory that uses Square's Moshi library for JSON serialization and deserialization. This converter enables type-safe conversion between Java objects and JSON for HTTP requests and responses in Retrofit 2 applications.
3

4
## Package Information
5

6
- **Package Name**: converter-moshi
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your `build.gradle`:
10

11
```gradle
12
implementation 'com.squareup.retrofit2:converter-moshi:3.0.0'
13
```
14

15
Maven:
16

17
```xml
18
<dependency>
19
  <groupId>com.squareup.retrofit2</groupId>
20
  <artifactId>converter-moshi</artifactId>
21
  <version>3.0.0</version>
22
</dependency>
23
```
24

25
## Core Imports
26

27
```java
28
import retrofit2.converter.moshi.MoshiConverterFactory;
29
import com.squareup.moshi.Moshi;
30
import retrofit2.Retrofit;
31
```
32

33
## Basic Usage
34

35
```java
36
import retrofit2.converter.moshi.MoshiConverterFactory;
37
import retrofit2.Retrofit;
38
import com.squareup.moshi.Moshi;
39

40
// Basic setup with default Moshi configuration
41
Retrofit retrofit = new Retrofit.Builder()
42
    .baseUrl("https://api.example.com/")
43
    .addConverterFactory(MoshiConverterFactory.create())
44
    .build();
45

46
// Advanced setup with custom Moshi instance
47
Moshi moshi = new Moshi.Builder()
48
    .add(new DateAdapter())
49
    .build();
50

51
Retrofit retrofit = new Retrofit.Builder()
52
    .baseUrl("https://api.example.com/")
53
    .addConverterFactory(MoshiConverterFactory.create(moshi))
54
    .build();
55

56
// Configuration options
57
Retrofit retrofit = new Retrofit.Builder()
58
    .baseUrl("https://api.example.com/")
59
    .addConverterFactory(
60
        MoshiConverterFactory.create(moshi)
61
            .asLenient()
62
            .failOnUnknown()
63
            .withNullSerialization()
64
            .withStreaming()
65
    )
66
    .build();
67
```
68

69
## Architecture
70

71
The Moshi converter integrates with Retrofit's converter factory system:
72

73
- **Factory Pattern**: `MoshiConverterFactory` creates appropriate converters for each request/response type
74
- **Type Safety**: Uses Moshi's `JsonAdapter<T>` system for compile-time type checking
75
- **Annotation Support**: Automatically handles Moshi's `@JsonQualifier` annotations
76
- **Configuration Chain**: Immutable builder pattern for customizing JSON processing behavior
77
- **Streaming Support**: Optional streaming serialization for large request bodies
78

79
## Capabilities
80

81
### Factory Creation
82

83
Creates `MoshiConverterFactory` instances with default or custom Moshi configurations.
84

85
```java { .api }
86
/**
87
 * Create an instance using a default Moshi instance for conversion.
88
 */
89
public static MoshiConverterFactory create();
90

91
/**
92
 * Create an instance using the provided Moshi instance for conversion.
93
 * @param moshi The Moshi instance to use for JSON processing
94
 * @throws NullPointerException if moshi is null
95
 */
96
public static MoshiConverterFactory create(Moshi moshi);
97
```
98

99
### Configuration Methods
100

101
Customize JSON processing behavior through method chaining. Each method returns a new factory instance.
102

103
```java { .api }
104
/**
105
 * Return a new factory which uses lenient adapters that are tolerant of malformed JSON.
106
 */
107
public MoshiConverterFactory asLenient();
108

109
/**
110
 * Return a new factory which uses adapters that fail when encountering unknown JSON properties.
111
 */
112
public MoshiConverterFactory failOnUnknown();
113

114
/**
115
 * Return a new factory which includes null values in the serialized JSON output.
116
 */
117
public MoshiConverterFactory withNullSerialization();
118

119
/**
120
 * Return a new factory which streams serialization of request messages to bytes on the HTTP thread.
121
 * This is either the calling thread for Call.execute(), or one of OkHttp's background threads 
122
 * for Call.enqueue(). Response bytes are always converted on OkHttp's background threads.
123
 */
124
public MoshiConverterFactory withStreaming();
125
```
126

127
### Converter Creation
128

129
Internal methods that Retrofit calls to create converters for specific types. You typically don't call these directly.
130

131
```java { .api }
132
/**
133
 * Creates a converter for response bodies of the specified type.
134
 * @param type The type to convert to
135
 * @param annotations Annotations on the method
136
 * @param retrofit The Retrofit instance
137
 * @return A converter for ResponseBody to the specified type, or null if not handled
138
 */
139
public Converter<ResponseBody, ?> responseBodyConverter(
140
    Type type, 
141
    Annotation[] annotations, 
142
    Retrofit retrofit
143
);
144

145
/**
146
 * Creates a converter for request bodies of the specified type.
147
 * @param type The type to convert from
148
 * @param parameterAnnotations Annotations on the parameter
149
 * @param methodAnnotations Annotations on the method
150
 * @param retrofit The Retrofit instance
151
 * @return A converter from the specified type to RequestBody, or null if not handled
152
 */
153
public Converter<?, RequestBody> requestBodyConverter(
154
    Type type,
155
    Annotation[] parameterAnnotations,
156
    Annotation[] methodAnnotations,
157
    Retrofit retrofit
158
);
159
```
160

161
## Types
162

163
```java { .api }
164
/**
165
 * The main converter factory class that extends Retrofit's Converter.Factory.
166
 * Instances are immutable and thread-safe.
167
 */
168
public final class MoshiConverterFactory extends Converter.Factory {
169
    // Factory methods and configuration methods as documented above
170
}
171
```
172

173
## Error Handling
174

175
The converter can throw the following exceptions:
176

177
- **`JsonDataException`**: Thrown by Moshi when JSON is malformed or when `failOnUnknown()` is enabled and unknown properties are encountered
178
- **`IOException`**: Thrown during I/O operations when reading response bodies or writing request bodies
179
- **`NullPointerException`**: Thrown when a null `Moshi` instance is passed to `create(Moshi)`
180

181
```java
182
// Example error handling
183
try {
184
    MyObject obj = apiService.getData().execute().body();
185
} catch (JsonDataException e) {
186
    // Handle malformed JSON or unknown properties
187
    System.err.println("JSON parsing error: " + e.getMessage());
188
} catch (IOException e) {
189
    // Handle network or I/O errors
190
    System.err.println("Network error: " + e.getMessage());
191
}
192
```
193

194
## Integration Notes
195

196
### Retrofit Configuration
197

198
- **Converter Order**: Add `MoshiConverterFactory` last in the converter chain as it handles all types by default
199
- **JsonQualifier Support**: Method and parameter annotations marked with `@JsonQualifier` are automatically used for adapter selection
200
- **Type Erasure**: Generic type information is preserved through Retrofit's `Type` parameter system
201

202
### Moshi Integration
203

204
- **Custom Adapters**: Configure custom `JsonAdapter` instances through the `Moshi.Builder`
205
- **Reflection**: Works with Moshi's reflection-based adapters for POJOs
206
- **Code Generation**: Compatible with Moshi's code generation for optimal performance
207

208
### Performance Considerations
209

210
- **Streaming**: Use `withStreaming()` for large request bodies to reduce memory usage
211
- **Thread Safety**: All factory instances are immutable and thread-safe
212
- **Adapter Caching**: Moshi adapters are cached internally for reuse across requests
213

214
### Requirements
215

216
- **Java**: Requires Java 8+ or Android API 21+
217
- **Dependencies**: Requires `retrofit2` and `com.squareup.moshi:moshi`
218
- **Optional**: `com.google.code.findbugs:jsr305` for additional annotations (compile-only)