0
# Third-Party Integrations
1

2
Integration annotations for popular frameworks including Jackson, Gson, and MongoDB with seamless serialization and repository generation. These integrations allow Immutables to work smoothly with existing Java ecosystem tools.
3

4
## Capabilities
5

6
### Jackson Integration
7

8
Integration with Jackson JSON processing library for seamless serialization.
9

10
```java { .api }
11
/**
12
 * Enable Jackson ObjectMapper serialization for immutable types.
13
 * Generates appropriate Jackson annotations (@JsonCreator, @JsonValue)
14
 * and delegation methods for TokenBuffer-based marshaling.
15
 */
16
@Target(ElementType.TYPE)
17
@Retention(RetentionPolicy.SOURCE)
18
@interface Jackson.Mapped {}
19
```
20

21
**Usage Example:**
22

23
```java
24
import org.immutables.value.Value;
25
import org.immutables.value.Jackson;
26
import com.fasterxml.jackson.databind.ObjectMapper;
27
import java.util.Optional;
28
import java.util.List;
29

30
@Value.Immutable
31
@Jackson.Mapped
32
public interface User {
33
  String username();
34
  String email();
35
  int age();
36
  Optional<String> fullName();
37
  List<String> roles();
38
}
39

40
// Jackson integration usage
41
ObjectMapper mapper = new ObjectMapper();
42

43
User user = ImmutableUser.builder()
44
    .username("alice")
45
    .email("alice@example.com")
46
    .age(30)
47
    .fullName("Alice Smith")
48
    .addRoles("user", "admin")
49
    .build();
50

51
// Serialize with Jackson
52
String json = mapper.writeValueAsString(user);
53

54
// Deserialize with Jackson
55
User restored = mapper.readValue(json, User.class);
56

57
// Works with Jackson modules and configurations
58
mapper.registerModule(new JavaTimeModule());
59
mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
60
```
61

62
### Gson Integration
63

64
Integration with Google Gson library for JSON serialization.
65

66
```java { .api }
67
/**
68
 * Generate Gson TypeAdapterFactory for immutable types.
69
 * Creates efficient type adapters that integrate with Gson's
70
 * serialization and deserialization system.
71
 */
72
@Target(ElementType.TYPE)
73
@Retention(RetentionPolicy.SOURCE)
74
@interface Gson.TypeAdapted {}
75

76
/**
77
 * Specify custom Gson field names (similar to @SerializedName).
78
 * Overrides the default field name used in JSON serialization.
79
 */
80
@Target(ElementType.METHOD)
81
@Retention(RetentionPolicy.SOURCE)
82
@interface Gson.Named {
83
  /** Custom field name for Gson serialization */
84
  String value();
85
}
86

87
/**
88
 * Specify expected subclasses for Gson polymorphic marshaling.
89
 * Enables Gson to handle inheritance hierarchies correctly.
90
 */
91
@Target(ElementType.TYPE)
92
@Retention(RetentionPolicy.SOURCE)
93
@interface Gson.Subclasses {
94
  /** Subclass types for polymorphic handling */
95
  Class<?>[] value();
96
}
97
```
98

99
**Usage Examples:**
100

101
```java
102
import org.immutables.value.Value;
103
import org.immutables.gson.Gson;
104
import java.util.List;
105
import java.util.Map;
106
import java.time.Instant;
107

108
// Basic Gson integration
109
@Value.Immutable
110
@Gson.TypeAdapted
111
public interface Product {
112
  String name();
113
  double price();
114
  List<String> categories();
115
}
116

117
// Custom field names
118
@Value.Immutable
119
@Gson.TypeAdapted
120
public interface ApiRequest {
121
  @Gson.Named("request_id")
122
  String requestId();
123
  
124
  @Gson.Named("user_data")
125
  Map<String, Object> userData();
126
  
127
  @Gson.Named("created_at")
128
  Instant createdAt();
129
}
130

131
// Polymorphic types
132
@Value.Immutable
133
@Gson.TypeAdapted
134
@Gson.Subclasses({Circle.class, Rectangle.class})
135
public interface Shape {
136
  String type();
137
  double area();
138
}
139

140
@Value.Immutable
141
@Gson.TypeAdapted
142
public interface Circle extends Shape {
143
  double radius();
144
  
145
  @Value.Default
146
  default String type() { return "circle"; }
147
  
148
  @Value.Derived
149
  default double area() { 
150
    return Math.PI * radius() * radius(); 
151
  }
152
}
153

154
// Gson usage
155
import com.google.gson.GsonBuilder;
156

157
GsonBuilder gsonBuilder = new GsonBuilder()
158
    .registerTypeAdapterFactory(new GsonAdaptersProduct())  // Generated factory
159
    .registerTypeAdapterFactory(new GsonAdaptersApiRequest())
160
    .registerTypeAdapterFactory(new GsonAdaptersShape());
161

162
com.google.gson.Gson gson = gsonBuilder.create();
163

164
Product product = ImmutableProduct.builder()
165
    .name("Laptop")
166
    .price(999.99)
167
    .addCategories("electronics", "computers")
168
    .build();
169

170
String json = gson.toJson(product);
171
Product restored = gson.fromJson(json, Product.class);
172
```
173

174
### MongoDB Integration
175

176
Generate MongoDB repositories and handle document mapping.
177

178
```java { .api }
179
/**
180
 * Generate MongoDB repository for immutable types.
181
 * Creates repository classes that integrate with MongoDB driver
182
 * for CRUD operations on immutable objects.
183
 */
184
@Target(ElementType.TYPE)
185
@Retention(RetentionPolicy.SOURCE)
186
@interface Mongo.Repository {
187
  /** 
188
   * MongoDB collection name. If empty, derives from type name.
189
   * @return collection name
190
   */
191
  String value() default "";
192
}
193

194
/**
195
 * Mark an attribute as MongoDB _id field.
196
 * The attribute will be mapped to MongoDB's _id field
197
 * and handled appropriately during serialization.
198
 */
199
@Target(ElementType.METHOD)
200
@Retention(RetentionPolicy.SOURCE)
201
@interface Mongo.Id {}
202
```
203

204
**Usage Example:**
205

206
```java
207
import org.immutables.value.Value;
208
import org.immutables.value.Mongo;
209
import com.mongodb.client.MongoDatabase;
210
import java.time.Instant;
211
import java.util.List;
212
import java.util.Optional;
213

214
@Value.Immutable
215
@Mongo.Repository("users")
216
public interface User {
217
  @Mongo.Id
218
  String id();
219
  
220
  String username();
221
  String email();
222
  Instant createdAt();
223
  List<String> tags();
224
  Optional<String> lastLogin();
225
}
226

227
// Generated repository usage
228
MongoDatabase database = mongoClient.getDatabase("myapp");
229
UserRepository userRepo = new UserRepository(database);
230

231
// Create user
232
User user = ImmutableUser.builder()
233
    .id("user123")
234
    .username("alice")
235
    .email("alice@example.com")
236
    .createdAt(Instant.now())
237
    .addTags("developer", "java")
238
    .build();
239

240
// Repository operations
241
userRepo.insert(user);
242
userRepo.save(user);
243

244
Optional<User> found = userRepo.findById("user123");
245
List<User> developers = userRepo.findByTag("developer");
246

247
User updated = user.withLastLogin(Instant.now().toString());
248
userRepo.update(updated);
249

250
userRepo.delete("user123");
251
```
252

253
### Generated Repository Methods
254

255
When `@Mongo.Repository` is applied, the annotation processor generates:
256

257
```java { .api }
258
// Generated repository class
259
public class UserRepository {
260
  public UserRepository(MongoDatabase database) { ... }
261
  
262
  // Basic CRUD operations
263
  public void insert(User user) { ... }
264
  public void save(User user) { ... }
265
  public Optional<User> findById(String id) { ... }
266
  public void update(User user) { ... }
267
  public void delete(String id) { ... }
268
  
269
  // Query methods based on attributes
270
  public List<User> findByUsername(String username) { ... }
271
  public List<User> findByEmail(String email) { ... }
272
  public List<User> findByTag(String tag) { ... }
273
  
274
  // Aggregation support
275
  public long count() { ... }
276
  public List<User> findAll() { ... }
277
  public List<User> findAll(int skip, int limit) { ... }
278
}
279
```
280

281
## Framework-Specific Features
282

283
### Jackson Advanced Features
284

285
```java
286
@Value.Immutable
287
@Jackson.Mapped
288
@JsonNaming(PropertyNamingStrategy.SnakeCaseStrategy.class)
289
@JsonIgnoreProperties(ignoreUnknown = true)
290
public interface AdvancedJacksonType {
291
  String firstName();
292
  String lastName();
293
  
294
  @JsonProperty("birth_date")
295
  LocalDate birthDate();
296
  
297
  @JsonIgnore
298
  String internalField();
299
}
300
```
301

302
### Gson Advanced Features
303

304
```java
305
@Value.Immutable
306
@Gson.TypeAdapted
307
public interface AdvancedGsonType {
308
  @Gson.Named("user_id")
309
  String userId();
310
  
311
  @SerializedName("created_timestamp") 
312
  long createdTimestamp();
313
  
314
  // Gson respects @Expose annotations
315
  @Expose(serialize = false)
316
  String secretData();
317
}
318
```
319

320
### MongoDB Advanced Features
321

322
```java
323
@Value.Immutable
324
@Mongo.Repository
325
public interface AdvancedMongoType {
326
  @Mongo.Id
327
  ObjectId id();
328
  
329
  String name();
330
  
331
  @BsonProperty("created_date")
332
  Date createdDate();
333
  
334
  @BsonIgnore
335
  String computedField();
336
  
337
  // Embedded documents
338
  Address address();
339
  
340
  // Collections
341
  List<Tag> tags();
342
}
343

344
@Value.Immutable
345
public interface Address {
346
  String street();
347
  String city();
348
  String country();
349
}
350

351
@Value.Immutable
352
public interface Tag {
353
  String name();
354
  String color();
355
}
356
```
357

358
## Integration Dependencies
359

360
To use these integrations, add the appropriate dependencies:
361

362
### Jackson
363

364
```xml
365
<dependency>
366
  <groupId>com.fasterxml.jackson.core</groupId>
367
  <artifactId>jackson-core</artifactId>
368
  <version>2.15.2</version>
369
</dependency>
370
```
371

372
### Gson
373

374
```xml
375
<dependency>
376
  <groupId>com.google.code.gson</groupId>
377
  <artifactId>gson</artifactId>
378
  <version>2.10.1</version>
379
</dependency>
380
```
381

382
### MongoDB
383

384
```xml
385
<dependency>
386
  <groupId>org.mongodb</groupId>
387
  <artifactId>mongodb-driver-sync</artifactId>
388
  <version>4.9.1</version>
389
</dependency>
390
```