0
# Route Declaration
1

2
Core functionality for defining HTTP endpoints using declarative annotations. Supports path-based and regex-based routing with comprehensive HTTP method and content-type configuration.
3

4
## Capabilities
5

6
### @Route Annotation
7

8
Primary annotation for defining reactive routes on methods. Provides comprehensive configuration options for HTTP routing, content types, and handler behavior.
9

10
```java { .api }
11
/**
12
 * Defines a reactive route on a method
13
 * Can be repeated using @Routes container annotation
14
 */
15
@Route(
16
    path = "/api/users/:id",           // Path-based routing with parameters
17
    regex = ".*\\.json$",              // Alternative regex-based routing  
18
    methods = HttpMethod.GET,          // HTTP methods (single or array)
19
    produces = {"application/json"},   // Response content types
20
    consumes = {"application/json"},   // Request content types
21
    type = Route.HandlerType.NORMAL,   // Handler execution type
22
    order = 100                        // Route ordering priority
23
)
24
public String handleRequest() {
25
    return "response";
26
}
27
```
28

29
**Usage Examples:**
30

31
```java
32
import io.quarkus.vertx.web.Route;
33
import io.quarkus.vertx.web.Route.HttpMethod;
34
import jakarta.enterprise.context.ApplicationScoped;
35

36
@ApplicationScoped
37
public class ProductRoutes {
38

39
    // Simple GET route
40
    @Route(path = "/products", methods = HttpMethod.GET)
41
    public String listProducts() {
42
        return "Product list";
43
    }
44

45
    // Route with path parameters
46
    @Route(path = "/products/:id", methods = HttpMethod.GET)
47
    public String getProduct(@Param("id") String productId) {
48
        return "Product: " + productId;
49
    }
50

51
    // Route with multiple HTTP methods
52
    @Route(path = "/products/:id", methods = {HttpMethod.PUT, HttpMethod.PATCH})
53
    public String updateProduct(@Param("id") String id, @Body Product product) {
54
        return "Updated product: " + id;
55
    }
56

57
    // Route with content type restrictions
58
    @Route(
59
        path = "/products", 
60
        methods = HttpMethod.POST,
61
        consumes = "application/json",
62
        produces = "application/json"
63
    )
64
    public String createProduct(@Body Product product) {
65
        return "Created: " + product.getName();
66
    }
67

68
    // Regex-based routing
69
    @Route(regex = "/files/.*\\.pdf$", methods = HttpMethod.GET)
70
    public String servePdf(RoutingExchange exchange) {
71
        String path = exchange.request().path();
72
        return "Serving PDF: " + path;
73
    }
74
}
75
```
76

77
### @Routes Container Annotation
78

79
Container annotation that allows multiple `@Route` annotations on a single method.
80

81
```java { .api }
82
/**
83
 * Container annotation for multiple @Route declarations on a single method
84
 * Automatically applied when using multiple @Route annotations
85
 */
86
@interface Routes {
87
    Route[] value();
88
}
89

90
// Usage - multiple @Route annotations are automatically wrapped in @Routes
91
@Route(path = "/api/v1/users", methods = HttpMethod.GET)
92
@Route(path = "/api/v2/users", methods = HttpMethod.GET)
93
public String getUsers() {
94
    return "Users";
95
}
96

97
// Explicit usage (equivalent to above)
98
@Routes({
99
    @Route(path = "/api/v1/users", methods = HttpMethod.GET),
100
    @Route(path = "/api/v2/users", methods = HttpMethod.GET)
101
})
102
public String getUsersExplicit() {
103
    return "Users";
104
}
105
```
106

107
### @RouteBase Class-Level Configuration
108

109
Provides default configuration for all routes declared within a class, reducing repetitive annotation parameters.
110

111
```java { .api }
112
/**
113
 * Configures default route settings for all routes in a class
114
 * Individual @Route annotations can override these defaults
115
 */
116
@RouteBase(
117
    path = "/api/v1",                    // Path prefix for all routes
118
    produces = {"application/json"},     // Default response content type
119
    consumes = {"application/json"}      // Default request content type
120
)
121
public class ApiController {
122
    
123
    @Route(path = "/users", methods = HttpMethod.GET)  // Becomes /api/v1/users
124
    public String getUsers() {
125
        return "Users";
126
    }
127
    
128
    @Route(path = "/products", methods = HttpMethod.GET, produces = "text/plain")  
129
    // Becomes /api/v1/products with overridden content type
130
    public String getProducts() {
131
        return "Products";
132
    }
133
}
134
```
135

136
## Configuration Enums
137

138
### HttpMethod Enum
139

140
Defines supported HTTP methods for route configuration.
141

142
```java { .api }
143
public enum Route.HttpMethod {
144
    GET,     // HTTP GET requests
145
    HEAD,    // HTTP HEAD requests  
146
    POST,    // HTTP POST requests
147
    PUT,     // HTTP PUT requests
148
    DELETE,  // HTTP DELETE requests
149
    OPTIONS  // HTTP OPTIONS requests
150
}
151
```
152

153
### HandlerType Enum
154

155
Specifies the execution model for route handlers.
156

157
```java { .api }
158
public enum Route.HandlerType {
159
    NORMAL,   // Non-blocking execution (default)
160
    BLOCKING, // Blocking execution on worker thread
161
    FAILURE;  // Failure handler for error processing
162
    
163
    /**
164
     * Convert string value to HandlerType
165
     * @param value String representation
166
     * @return Corresponding HandlerType
167
     */
168
    public static HandlerType from(String value);
169
}
170
```
171

172
**Handler Type Usage:**
173

174
```java
175
// Non-blocking handler (default)
176
@Route(path = "/async", methods = HttpMethod.GET, type = Route.HandlerType.NORMAL)
177
public Uni<String> asyncOperation() {
178
    return Uni.createFrom().item("Async result");
179
}
180

181
// Blocking handler for I/O operations
182
@Route(path = "/blocking", methods = HttpMethod.GET, type = Route.HandlerType.BLOCKING)
183
public String blockingOperation() {
184
    // Blocking I/O operation
185
    return "Blocking result";
186
}
187

188
// Failure handler
189
@Route(path = "/error-handler", type = Route.HandlerType.FAILURE)
190
public String handleError(RoutingExchange exchange) {
191
    Throwable failure = exchange.context().failure();
192
    return "Error: " + failure.getMessage();
193
}
194
```
195

196
## Routing Patterns
197

198
### Path-Based Routing
199

200
Standard path-based routing with support for path parameters and wildcards.
201

202
```java
203
// Static path
204
@Route(path = "/users", methods = HttpMethod.GET)
205

206
// Path with single parameter
207
@Route(path = "/users/:id", methods = HttpMethod.GET)
208

209
// Path with multiple parameters  
210
@Route(path = "/users/:userId/posts/:postId", methods = HttpMethod.GET)
211

212
// Wildcard matching
213
@Route(path = "/files/*", methods = HttpMethod.GET)
214
```
215

216
### Regex-Based Routing
217

218
Advanced routing using regular expressions for complex path matching.
219

220
```java
221
// File extension matching
222
@Route(regex = ".*\\.json$", methods = HttpMethod.GET)
223

224
// Version-specific API matching
225
@Route(regex = "/api/v[0-9]+/users", methods = HttpMethod.GET)
226

227
// Complex pattern matching
228
@Route(regex = "/products/[a-zA-Z0-9]{8,12}", methods = HttpMethod.GET)
229
```
230

231
### Route Ordering
232

233
Control route evaluation order using the `order` attribute. Lower values are evaluated first.
234

235
```java
236
@Route(path = "/special/*", methods = HttpMethod.GET, order = 1)
237
public String specialHandler() { return "Special"; }
238

239
@Route(path = "/*", methods = HttpMethod.GET, order = 1000)  
240
public String fallbackHandler() { return "Fallback"; }
241
```
242

243
### @RouteBase Annotation
244

245
Class-level annotation that provides defaults for all route methods within a class, reducing repetition and providing consistent configuration.
246

247
```java { .api }
248
/**
249
 * Annotation for configuring class-level defaults for reactive routes
250
 */
251
@RouteBase(
252
    path = "/api/v1",                    // Path prefix for all routes in class
253
    produces = {"application/json"},     // Default response content type
254
    consumes = {"application/json"}      // Default request content type
255
)
256
public @interface RouteBase {
257
    String path() default "";
258
    String[] produces() default {};
259
    String[] consumes() default {};
260
}
261
```
262

263
**Usage Examples:**
264

265
```java
266
import io.quarkus.vertx.web.Route;
267
import io.quarkus.vertx.web.RouteBase;
268
import io.quarkus.vertx.web.Route.HttpMethod;
269
import jakarta.enterprise.context.ApplicationScoped;
270

271
@ApplicationScoped
272
@RouteBase(path = "/api/users", produces = "application/json")
273
public class UserRoutes {
274

275
    // Effective path: /api/users (base + empty path)
276
    @Route(methods = HttpMethod.GET)
277
    public String listUsers() {
278
        return "{\"users\": []}";
279
    }
280

281
    // Effective path: /api/users/:id (base + relative path)
282
    @Route(path = "/:id", methods = HttpMethod.GET)
283
    public String getUser(@Param("id") String id) {
284
        return "{\"user\": {\"id\": \"" + id + "\"}}";
285
    }
286

287
    // Override base produces setting
288
    @Route(path = "/:id/avatar", methods = HttpMethod.GET, produces = "image/png")
289
    public byte[] getUserAvatar(@Param("id") String id) {
290
        return loadAvatarBytes(id);
291
    }
292
}
293
```