0
# Quarkus JSON-B Extension
1

2
The Quarkus JSON-B extension provides comprehensive JSON-B (JSON Binding) support for Java applications built with the Quarkus framework. It integrates Eclipse Yasson as the underlying JSON-B implementation and enables automatic serialization and deserialization of Java objects to and from JSON format with full CDI integration.
3

4
## Package Information
5

6
- **Package Name**: quarkus-jsonb
7
- **Package Type**: maven
8
- **Group ID**: io.quarkus
9
- **Artifact ID**: quarkus-jsonb
10
- **Language**: Java
11
- **Installation**: Add dependency to Maven POM or Gradle build file
12

13
Maven:
14
```xml
15
<dependency>
16
    <groupId>io.quarkus</groupId>
17
    <artifactId>quarkus-jsonb</artifactId>
18
</dependency>
19
```
20

21
Gradle:
22
```gradle
23
implementation 'io.quarkus:quarkus-jsonb'
24
```
25

26
## Core Imports
27

28
```java
29
import jakarta.json.bind.Jsonb;
30
import jakarta.json.bind.JsonbConfig;
31
import jakarta.json.bind.config.PropertyNamingStrategy;
32
import io.quarkus.jsonb.JsonbConfigCustomizer;
33
```
34

35
For SPI usage (extension developers):
36
```java
37
import io.quarkus.jsonb.spi.JsonbSerializerBuildItem;
38
import io.quarkus.jsonb.spi.JsonbDeserializerBuildItem;
39
```
40

41
## Basic Usage
42

43
```java
44
import jakarta.inject.Inject;
45
import jakarta.json.bind.Jsonb;
46

47
@ApplicationScoped
48
public class JsonService {
49

50
    @Inject
51
    Jsonb jsonb;
52

53
    public String serialize(Object obj) {
54
        return jsonb.toJson(obj);
55
    }
56

57
    public <T> T deserialize(String json, Class<T> type) {
58
        return jsonb.fromJson(json, type);
59
    }
60
}
61
```
62

63
## Capabilities
64

65
### JSON-B Bean Injection
66

67
The extension automatically provides CDI beans for JSON-B operations.
68

69
```java { .api }
70
@Inject
71
Jsonb jsonb;
72
```
73

74
The Jsonb bean is available for injection and configured with any custom JsonbConfigCustomizer beans.
75

76
```java { .api }
77
@Inject 
78
JsonbConfig jsonbConfig;
79
```
80

81
The JsonbConfig bean is also available for injection (Dependent scope).
82

83
### Custom Configuration
84

85
Customize JSON-B configuration by implementing JsonbConfigCustomizer.
86

87
```java { .api }
88
public interface JsonbConfigCustomizer {
89
    void customize(JsonbConfig jsonbConfig);
90
}
91
```
92

93
Example implementation:
94

95
```java
96
@Singleton
97
public class MyJsonbCustomizer implements JsonbConfigCustomizer {
98
    @Override
99
    public void customize(JsonbConfig config) {
100
        config.withFormatting(true)
101
              .withNullValues(false)
102
              .withPropertyNamingStrategy(PropertyNamingStrategy.LOWER_CASE_WITH_UNDERSCORES);
103
    }
104
}
105
```
106

107
### CDI-Aware Component Creation
108

109
The extension provides CDI-aware component instance creation for JSON-B components.
110

111
```java { .api }
112
public class QuarkusJsonbComponentInstanceCreator implements JsonbComponentInstanceCreator {
113
    public QuarkusJsonbComponentInstanceCreator();
114
    public void close() throws IOException;
115
    public <T> T getOrCreateComponent(Class<T> componentClass);
116
}
117
```
118

119
This class automatically integrates with Quarkus CDI to create JSON-B serializers, deserializers, and adapters as CDI beans when possible.
120

121
### Automatic Adapter Registration
122

123
JSON-B adapters are automatically discovered and registered when they are CDI beans.
124

125
```java
126
@Singleton
127
public class InstantAdapter implements JsonbAdapter<Instant, Long> {
128
    @Override
129
    public Long adaptToJson(Instant instant) {
130
        return instant.getEpochSecond();
131
    }
132

133
    @Override
134
    public Instant adaptFromJson(Long epochSecond) {
135
        return Instant.ofEpochSecond(epochSecond);
136
    }
137
}
138
```
139

140
### Extension SPI (For Extension Developers)
141

142
The extension provides build items for registering custom serializers and deserializers.
143

144
```java { .api }
145
public final class JsonbSerializerBuildItem extends MultiBuildItem {
146
    public JsonbSerializerBuildItem(String serializerClassName);
147
    public JsonbSerializerBuildItem(Collection<String> serializerClassNames);
148
    public Collection<String> getSerializerClassNames();
149
}
150
```
151

152
```java { .api }
153
public final class JsonbDeserializerBuildItem extends MultiBuildItem {
154
    public JsonbDeserializerBuildItem(String deserializerClassName);
155
    public JsonbDeserializerBuildItem(Collection<String> deserializerClassNames);
156
    public Collection<String> getDeserializerClassNames();
157
}
158
```
159

160
Example usage in an extension deployment class:
161

162
```java
163
@BuildStep
164
void registerCustomSerializers(BuildProducer<JsonbSerializerBuildItem> serializers) {
165
    serializers.produce(new JsonbSerializerBuildItem(MyCustomSerializer.class.getName()));
166
}
167
```
168

169
## Types
170

171
```java { .api }
172
// Main producer class providing JSON-B beans
173
@Singleton
174
public class JsonbProducer {
175
    @Produces @Dependent @DefaultBean
176
    public JsonbConfig jsonbConfig(@All List<JsonbConfigCustomizer> customizers);
177
    
178
    @Produces @Singleton @DefaultBean  
179
    public Jsonb jsonb(JsonbConfig jsonbConfig);
180
}
181
```
182

183
```java { .api }
184
// Interface for customizing JSON-B configuration
185
public interface JsonbConfigCustomizer {
186
    void customize(JsonbConfig jsonbConfig);
187
}
188
```
189

190
```java { .api }
191
// CDI-aware component instance creator
192
public class QuarkusJsonbComponentInstanceCreator implements JsonbComponentInstanceCreator {
193
    public QuarkusJsonbComponentInstanceCreator();
194
    public void close() throws IOException;
195
    public <T> T getOrCreateComponent(Class<T> componentClass);
196
}
197
```
198

199
```java { .api }
200
// Build items for extension developers  
201
public final class JsonbSerializerBuildItem extends MultiBuildItem {
202
    public JsonbSerializerBuildItem(String serializerClassName);
203
    public JsonbSerializerBuildItem(Collection<String> serializerClassNames);
204
    public Collection<String> getSerializerClassNames();
205
}
206

207
public final class JsonbDeserializerBuildItem extends MultiBuildItem {
208
    public JsonbDeserializerBuildItem(String deserializerClassName);
209
    public JsonbDeserializerBuildItem(Collection<String> deserializerClassNames);
210
    public Collection<String> getDeserializerClassNames();
211
}
212
```
213

214
## Dependencies
215

216
The extension automatically includes and integrates with these components:
217

218
```java { .api }
219
// Required dependencies (automatically included):
220
// - io.quarkus:quarkus-jsonp (JSON Processing support)
221
// - org.eclipse:yasson (Eclipse Yasson JSON-B implementation)  
222
// - io.quarkus:quarkus-arc (CDI support)
223
```
224

225
When you add `quarkus-jsonb` to your project, these dependencies are automatically managed.
226

227
## Architecture
228

229
The extension operates through several key components:
230

231
- **JsonbProducer**: CDI producer class that creates the main Jsonb and JsonbConfig beans
232
- **JsonbConfigCustomizer**: Interface for providing custom configuration
233
- **QuarkusJsonbComponentInstanceCreator**: CDI-aware factory for JSON-B components
234
- **Build Items**: SPI classes for extension developers to register custom serializers/deserializers
235

236
The extension automatically:
237
- Registers Eclipse Yasson as the JSON-B provider
238
- Creates CDI beans for Jsonb and JsonbConfig
239
- Discovers and registers JsonbAdapter beans
240
- Registers reflection metadata for native image compilation
241
- Integrates with Quarkus JSON-P extension for JSON provider support
242

243
## Error Handling
244

245
Custom serializers and deserializers must have public no-argument constructors. If CDI bean creation fails, the extension falls back to direct instantiation via reflection.
246

247
The extension throws `IllegalStateException` if JSON-B component instantiation fails during fallback creation.