0
# Parameter Injection
1

2
System for extracting request data including path parameters, query parameters, HTTP headers, and request body content with automatic type conversion and validation support.
3

4
## Capabilities
5

6
### @Param Annotation
7

8
Injects request parameters (path parameters and query parameters) into route method parameters with automatic type conversion support.
9

10
```java { .api }
11
/**
12
 * Injects request parameters into method parameters
13
 * Supports path parameters (from route path) and query parameters
14
 * @param value Parameter name, or ELEMENT_NAME constant for automatic naming
15
 */
16
@Param("parameterName")
17
// Supported parameter types:
18
// - String: Direct parameter value
19
// - Optional<String>: Optional parameter value  
20
// - List<String>: Multiple parameter values
21

22
public static final String ELEMENT_NAME = "<<element name>>";
23
```
24

25
**Usage Examples:**
26

27
```java
28
import io.quarkus.vertx.web.Route;
29
import io.quarkus.vertx.web.Param;
30
import java.util.Optional;
31
import java.util.List;
32

33
@ApplicationScoped
34
public class ParameterExamples {
35

36
    // Path parameter injection
37
    @Route(path = "/users/:userId", methods = HttpMethod.GET)
38
    public String getUser(@Param("userId") String userId) {
39
        return "User ID: " + userId;
40
    }
41

42
    // Multiple path parameters
43
    @Route(path = "/users/:userId/posts/:postId", methods = HttpMethod.GET)
44
    public String getUserPost(
45
        @Param("userId") String userId,
46
        @Param("postId") String postId
47
    ) {
48
        return "User: " + userId + ", Post: " + postId;
49
    }
50

51
    // Query parameter injection
52
    @Route(path = "/search", methods = HttpMethod.GET)
53
    public String search(
54
        @Param("q") String query,
55
        @Param("limit") Optional<String> limit,
56
        @Param("sort") Optional<String> sortOrder
57
    ) {
58
        int limitValue = limit.map(Integer::parseInt).orElse(10);
59
        return "Query: " + query + ", Limit: " + limitValue;
60
    }
61

62
    // Multiple values for same parameter
63
    @Route(path = "/filter", methods = HttpMethod.GET)
64
    public String filter(@Param("category") List<String> categories) {
65
        return "Categories: " + String.join(", ", categories);
66
    }
67

68
    // Automatic parameter name resolution
69
    @Route(path = "/auto/:name", methods = HttpMethod.GET)
70
    public String autoParam(@Param(Param.ELEMENT_NAME) String name) {
71
        // Parameter name automatically resolved from method parameter name
72
        return "Name: " + name;
73
    }
74
}
75
```
76

77
### @Header Annotation
78

79
Injects HTTP headers into route method parameters with support for single and multiple header values.
80

81
```java { .api }
82
/**
83
 * Injects HTTP headers into method parameters
84
 * @param value Header name, or ELEMENT_NAME constant for automatic naming
85
 */
86
@Header("headerName")
87
// Supported parameter types:
88
// - String: Single header value
89
// - Optional<String>: Optional header value
90
// - List<String>: Multiple header values (for headers that can appear multiple times)
91

92
public static final String ELEMENT_NAME = "<<element name>>";
93
```
94

95
**Usage Examples:**
96

97
```java
98
import io.quarkus.vertx.web.Header;
99

100
@ApplicationScoped
101
public class HeaderExamples {
102

103
    // Single header injection
104
    @Route(path = "/protected", methods = HttpMethod.GET)
105
    public String protectedEndpoint(@Header("Authorization") String authHeader) {
106
        if (authHeader.startsWith("Bearer ")) {
107
            return "Authorized";
108
        }
109
        return "Unauthorized";
110
    }
111

112
    // Optional header injection
113
    @Route(path = "/content", methods = HttpMethod.GET)
114
    public String getContent(
115
        @Header("Accept") Optional<String> acceptHeader,
116
        @Header("User-Agent") Optional<String> userAgent
117
    ) {
118
        String accept = acceptHeader.orElse("*/*");
119
        String agent = userAgent.orElse("Unknown");
120
        return "Accept: " + accept + ", User-Agent: " + agent;
121
    }
122

123
    // Multiple header values
124
    @Route(path = "/cors", methods = HttpMethod.OPTIONS)
125
    public String handleCors(@Header("Access-Control-Request-Headers") List<String> requestHeaders) {
126
        return "Requested headers: " + String.join(", ", requestHeaders);
127
    }
128

129
    // Custom headers
130
    @Route(path = "/api/data", methods = HttpMethod.GET)
131
    public String getData(
132
        @Header("X-API-Key") String apiKey,
133
        @Header("X-Request-ID") Optional<String> requestId
134
    ) {
135
        String reqId = requestId.orElse("generated-id");
136
        return "API Key: " + apiKey + ", Request ID: " + reqId;
137
    }
138
}
139
```
140

141
### @Body Annotation
142

143
Injects request body content into route method parameters with automatic deserialization support for various content types.
144

145
```java { .api }
146
/**
147
 * Injects request body into method parameters
148
 * Supports automatic deserialization based on content type
149
 */
150
@Body
151
// Supported parameter types:
152
// - io.vertx.core.buffer.Buffer: Raw body content
153
// - String: Body as string
154
// - io.vertx.core.json.JsonObject: JSON object body
155
// - io.vertx.core.json.JsonArray: JSON array body  
156
// - Custom objects: Automatic JSON deserialization via Jackson
157
```
158

159
**Usage Examples:**
160

161
```java
162
import io.quarkus.vertx.web.Body;
163
import io.vertx.core.buffer.Buffer;
164
import io.vertx.core.json.JsonObject;
165
import io.vertx.core.json.JsonArray;
166

167
@ApplicationScoped
168
public class BodyExamples {
169

170
    // String body injection
171
    @Route(path = "/text", methods = HttpMethod.POST, consumes = "text/plain")
172
    public String handleText(@Body String textContent) {
173
        return "Received text: " + textContent;
174
    }
175

176
    // Raw buffer body injection
177
    @Route(path = "/binary", methods = HttpMethod.POST, consumes = "application/octet-stream")
178
    public String handleBinary(@Body Buffer binaryData) {
179
        return "Received " + binaryData.length() + " bytes";
180
    }
181

182
    // JSON object body injection
183
    @Route(path = "/json", methods = HttpMethod.POST, consumes = "application/json")
184
    public String handleJsonObject(@Body JsonObject jsonData) {
185
        String name = jsonData.getString("name", "Unknown");
186
        return "Received JSON with name: " + name;
187
    }
188

189
    // JSON array body injection
190
    @Route(path = "/batch", methods = HttpMethod.POST, consumes = "application/json")
191
    public String handleJsonArray(@Body JsonArray jsonArray) {
192
        return "Received array with " + jsonArray.size() + " items";
193
    }
194

195
    // Custom object body injection (automatic JSON deserialization)
196
    @Route(path = "/users", methods = HttpMethod.POST, consumes = "application/json")
197
    public String createUser(@Body User user) {
198
        return "Created user: " + user.getName() + " (" + user.getEmail() + ")";
199
    }
200

201
    // Complex object with nested properties
202
    @Route(path = "/orders", methods = HttpMethod.POST, consumes = "application/json")
203
    public String createOrder(@Body Order order) {
204
        return "Created order for " + order.getCustomer().getName() + 
205
               " with " + order.getItems().size() + " items";
206
    }
207
}
208

209
// Example domain classes for JSON deserialization
210
public class User {
211
    private String name;
212
    private String email;
213
    private int age;
214
    
215
    // Getters and setters
216
    public String getName() { return name; }
217
    public void setName(String name) { this.name = name; }
218
    public String getEmail() { return email; }
219
    public void setEmail(String email) { this.email = email; }
220
    public int getAge() { return age; }
221
    public void setAge(int age) { this.age = age; }
222
}
223

224
public class Order {
225
    private Customer customer;
226
    private List<OrderItem> items;
227
    private BigDecimal total;
228
    
229
    // Getters and setters
230
    public Customer getCustomer() { return customer; }
231
    public void setCustomer(Customer customer) { this.customer = customer; }
232
    public List<OrderItem> getItems() { return items; }
233
    public void setItems(List<OrderItem> items) { this.items = items; }
234
    public BigDecimal getTotal() { return total; }
235
    public void setTotal(BigDecimal total) { this.total = total; }
236
}
237
```
238

239
## Combined Parameter Injection
240

241
Multiple injection types can be combined in a single method for comprehensive request data access.
242

243
```java
244
@Route(path = "/api/users/:userId", methods = HttpMethod.PUT, consumes = "application/json")
245
public String updateUser(
246
    @Param("userId") String userId,                    // Path parameter
247
    @Param("version") Optional<String> version,        // Query parameter
248
    @Header("Authorization") String authHeader,        // HTTP header
249
    @Header("Content-Type") String contentType,        // Content type header
250
    @Body User updatedUser                            // Request body
251
) {
252
    // Validate authorization
253
    if (!authHeader.startsWith("Bearer ")) {
254
        return "Unauthorized";
255
    }
256
    
257
    // Check version for optimistic locking
258
    int versionNum = version.map(Integer::parseInt).orElse(1);
259
    
260
    // Update user logic
261
    return "Updated user " + userId + " to version " + (versionNum + 1);
262
}
263
```
264

265
## Parameter Validation
266

267
While the reactive routes extension doesn't provide built-in validation, it integrates well with Bean Validation (JSR-303) annotations:
268

269
```java
270
import jakarta.validation.Valid;
271
import jakarta.validation.constraints.NotNull;
272
import jakarta.validation.constraints.Email;
273

274
@Route(path = "/users", methods = HttpMethod.POST, consumes = "application/json")
275
public String createUser(@Valid @Body User user) {
276
    return "Created valid user: " + user.getName();
277
}
278

279
public class User {
280
    @NotNull
281
    private String name;
282
    
283
    @Email
284
    private String email;
285
    
286
    // Getters and setters with validation annotations
287
}
288
```
289

290
## Type Conversion
291

292
The extension automatically handles type conversion for basic types when using `@Param`:
293

294
```java
295
// String to numeric conversion
296
@Route(path = "/items/:id", methods = HttpMethod.GET)
297
public String getItem(@Param("id") String itemId) {
298
    long id = Long.parseLong(itemId);  // Manual conversion needed
299
    return "Item: " + id;
300
}
301

302
// Boolean parameter handling
303
@Route(path = "/search", methods = HttpMethod.GET)
304
public String search(
305
    @Param("q") String query,
306
    @Param("includeInactive") Optional<String> includeInactive
307
) {
308
    boolean includeFlag = includeInactive
309
        .map("true"::equalsIgnoreCase)
310
        .orElse(false);
311
    return "Search: " + query + ", Include inactive: " + includeFlag;
312
}
313
```