0
# Quality of Service Management
1

2
**⚠️ DEPRECATED: This filter is deprecated. Use `org.eclipse.jetty.server.handler.QoSHandler` instead.**
3

4
Quality of Service filter for limiting concurrent requests with priority-based queuing and suspension. This filter helps manage server resources by controlling the number of simultaneous requests being processed.
5

6
## Capabilities
7

8
### QoSFilter
9

10
Filter for managing request concurrency and quality of service.
11

12
```java { .api }
13
/**
14
 * Quality of Service filter for limiting concurrent requests.
15
 * Provides priority-based queuing and request suspension capabilities.
16
 */
17
public class QoSFilter implements Filter {
18
    /**
19
     * Initialize the filter with configuration parameters
20
     * @param filterConfig Filter configuration
21
     */
22
    public void init(FilterConfig filterConfig);
23
    
24
    /**
25
     * Process requests with QoS management
26
     * @param request The servlet request
27
     * @param response The servlet response
28
     * @param chain The filter chain
29
     * @throws IOException if I/O error occurs
30
     * @throws ServletException if servlet error occurs
31
     */
32
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) 
33
        throws IOException, ServletException;
34
    
35
    /**
36
     * Clean up filter resources  
37
     */
38
    public void destroy();
39
    
40
    /**
41
     * Get the wait time before request suspension
42
     * @return Wait time in milliseconds
43
     */
44
    public long getWaitMs();
45
    
46
    /**
47
     * Get the suspension timeout period
48
     * @return Suspension timeout in milliseconds
49
     */
50
    public long getSuspendMs();
51
    
52
    /**
53
     * Get the maximum number of concurrent requests allowed
54
     * @return Maximum concurrent requests
55
     */
56
    public int getMaxRequests();
57
    
58
    /**
59
     * Get the priority of the given request (for subclass extension)
60
     * @param request The servlet request
61
     * @return Priority level (higher numbers = higher priority)
62
     */
63
    protected int getPriority(ServletRequest request);
64
}
65
```
66

67
### Configuration Constants
68

69
Parameter name constants for filter configuration.
70

71
```java { .api }
72
public static final String MANAGED_ATTR_INIT_PARAM = "managedAttr";
73
public static final String MAX_REQUESTS_INIT_PARAM = "maxRequests";
74
public static final String MAX_PRIORITY_INIT_PARAM = "maxPriority";
75
public static final String MAX_WAIT_INIT_PARAM = "waitMs";
76
public static final String SUSPEND_INIT_PARAM = "suspendMs";
77
```
78

79
## Configuration Parameters
80

81
### maxRequests
82
**Type**: Integer  
83
**Default**: `10`  
84
**Description**: Maximum number of requests that can be processed concurrently.
85

86
### maxPriority  
87
**Type**: Integer  
88
**Default**: `10`  
89
**Description**: Maximum priority level for request prioritization.
90

91
### waitMs
92
**Type**: Long  
93
**Default**: `50`  
94
**Description**: Time in milliseconds to wait before suspending a request when max concurrent requests is reached.
95

96
### suspendMs
97
**Type**: Long  
98
**Default**: `-1` (container default)  
99
**Description**: Timeout in milliseconds for suspended requests. -1 uses container default timeout.
100

101
### managedAttr
102
**Type**: Boolean  
103
**Default**: `false`  
104
**Description**: Whether to register the filter as a managed attribute in the ServletContext.
105

106
## Usage Examples
107

108
### Basic QoS Configuration
109

110
```xml
111
<!-- Web.xml configuration -->
112
<filter>
113
    <filter-name>QoSFilter</filter-name>
114
    <filter-class>org.eclipse.jetty.ee10.servlets.QoSFilter</filter-class>
115
    <init-param>
116
        <param-name>maxRequests</param-name>
117
        <param-value>20</param-value>
118
    </init-param>
119
    <init-param>
120
        <param-name>waitMs</param-name>
121
        <param-value>100</param-value>
122
    </init-param>
123
    <init-param>
124
        <param-name>suspendMs</param-name>
125
        <param-value>30000</param-value>
126
    </init-param>
127
</filter>
128
<filter-mapping>
129
    <filter-name>QoSFilter</filter-name>
130
    <url-pattern>/api/*</url-pattern>
131
</filter-mapping>
132
```
133

134
### High-Capacity Configuration
135

136
```xml
137
<filter>
138
    <filter-name>HighCapacityQoS</filter-name>
139
    <filter-class>org.eclipse.jetty.ee10.servlets.QoSFilter</filter-class>
140
    <init-param>
141
        <param-name>maxRequests</param-name>
142
        <param-value>100</param-value>
143
    </init-param>
144
    <init-param>
145
        <param-name>waitMs</param-name>
146
        <param-value>25</param-value>
147
    </init-param>
148
    <init-param>
149
        <param-name>suspendMs</param-name>
150
        <param-value>60000</param-value>
151
    </init-param>
152
    <init-param>
153
        <param-name>maxPriority</param-name>
154
        <param-value>20</param-value>
155
    </init-param>
156
</filter>
157
```
158

159
### Conservative QoS Configuration
160

161
```xml
162
<!-- For resource-constrained environments -->
163
<filter>
164
    <filter-name>ConservativeQoS</filter-name>
165
    <filter-class>org.eclipse.jetty.ee10.servlets.QoSFilter</filter-class>
166
    <init-param>
167
        <param-name>maxRequests</param-name>
168
        <param-value>5</param-value>
169
    </init-param>
170
    <init-param>
171
        <param-name>waitMs</param-name>
172
        <param-value>200</param-value>
173
    </init-param>
174
    <init-param>
175
        <param-name>suspendMs</param-name>
176
        <param-value>10000</param-value>
177
    </init-param>
178
</filter>
179
```
180

181
### Managed Attribute Configuration
182

183
```xml
184
<!-- Enable JMX management -->
185
<filter>
186
    <filter-name>ManagedQoSFilter</filter-name>
187
    <filter-class>org.eclipse.jetty.ee10.servlets.QoSFilter</filter-class>
188
    <init-param>
189
        <param-name>maxRequests</param-name>
190
        <param-value>50</param-value>
191
    </init-param>
192
    <init-param>
193
        <param-name>managedAttr</param-name>
194
        <param-value>true</param-value>
195
    </init-param>
196
</filter>
197
```
198

199
### Custom Priority QoS Filter
200

201
```java
202
import org.eclipse.jetty.ee10.servlets.QoSFilter;
203
import jakarta.servlet.ServletRequest;
204
import jakarta.servlet.http.HttpServletRequest;
205

206
/**
207
 * Custom QoS filter that prioritizes requests based on user roles
208
 */
209
public class PriorityQoSFilter extends QoSFilter {
210
    @Override
211
    protected int getPriority(ServletRequest request) {
212
        if (request instanceof HttpServletRequest) {
213
            HttpServletRequest httpRequest = (HttpServletRequest) request;
214
            
215
            // Check user role for priority
216
            String userRole = getUserRole(httpRequest);
217
            
218
            switch (userRole) {
219
                case "ADMIN":
220
                    return 10; // Highest priority
221
                case "PREMIUM":
222
                    return 7;  // High priority
223
                case "USER": 
224
                    return 5;  // Normal priority
225
                case "GUEST":
226
                    return 2;  // Low priority  
227
                default:
228
                    return 1;  // Lowest priority
229
            }
230
        }
231
        
232
        return super.getPriority(request);
233
    }
234
    
235
    private String getUserRole(HttpServletRequest request) {
236
        // Implementation-specific role extraction
237
        // Could check session, JWT token, headers, etc.
238
        String authHeader = request.getHeader("Authorization");
239
        if (authHeader != null && authHeader.startsWith("Bearer ")) {
240
            return JwtUtils.extractRole(authHeader.substring(7));
241
        }
242
        
243
        return "GUEST";
244
    }
245
}
246
```
247

248
### API Endpoint Priority Filter
249

250
```java
251
/**
252
 * QoS filter that prioritizes based on API endpoint criticality
253
 */
254
public class ApiPriorityQoSFilter extends QoSFilter {
255
    @Override
256
    protected int getPriority(ServletRequest request) {
257
        if (request instanceof HttpServletRequest) {
258
            HttpServletRequest httpRequest = (HttpServletRequest) request;
259
            String path = httpRequest.getRequestURI();
260
            
261
            // Critical system endpoints get highest priority
262
            if (path.startsWith("/api/health") || path.startsWith("/api/status")) {
263
                return 10;
264
            }
265
            
266
            // Admin endpoints get high priority
267
            if (path.startsWith("/api/admin")) {
268
                return 8;
269
            }
270
            
271
            // User management gets medium-high priority
272
            if (path.startsWith("/api/user") || path.startsWith("/api/auth")) {
273
                return 6;
274
            }
275
            
276
            // Data endpoints get medium priority
277
            if (path.startsWith("/api/data")) {
278
                return 5;
279
            }
280
            
281
            // Reporting endpoints get lower priority
282
            if (path.startsWith("/api/reports")) {
283
                return 3;
284
            }
285
            
286
            // All other endpoints get default priority
287
            return 4;
288
        }
289
        
290
        return super.getPriority(request);
291
    }
292
}
293
```
294

295
### Programmatic Configuration
296

297
```java
298
import org.eclipse.jetty.ee10.servlets.QoSFilter;
299
import jakarta.servlet.FilterRegistration;
300
import jakarta.servlet.ServletContext;
301

302
public class QoSConfig {
303
    public static void configureQoSFilter(ServletContext context) {
304
        FilterRegistration.Dynamic qosFilter = context.addFilter("QoSFilter", QoSFilter.class);
305
        
306
        qosFilter.setInitParameter(QoSFilter.MAX_REQUESTS_INIT_PARAM, "25");
307
        qosFilter.setInitParameter(QoSFilter.MAX_WAIT_INIT_PARAM, "75");
308
        qosFilter.setInitParameter(QoSFilter.SUSPEND_INIT_PARAM, "45000");
309
        qosFilter.setInitParameter(QoSFilter.MAX_PRIORITY_INIT_PARAM, "15");
310
        qosFilter.setInitParameter(QoSFilter.MANAGED_ATTR_INIT_PARAM, "true");
311
        
312
        qosFilter.addMappingForUrlPatterns(null, false, "/api/*", "/services/*");
313
    }
314
    
315
    public static void configureCustomPriorityFilter(ServletContext context) {
316
        FilterRegistration.Dynamic priorityFilter = context.addFilter("PriorityQoSFilter", 
317
                                                                      PriorityQoSFilter.class);
318
        
319
        priorityFilter.setInitParameter("maxRequests", "15");
320
        priorityFilter.setInitParameter("waitMs", "100");
321
        priorityFilter.setInitParameter("suspendMs", "30000");
322
        
323
        priorityFilter.addMappingForUrlPatterns(null, false, "/*");
324
    }
325
}
326
```
327

328
## QoS Processing Flow
329

330
### Request Processing Steps
331

332
1. **Request Arrival**: Filter receives incoming request
333
2. **Priority Calculation**: `getPriority()` method determines request priority
334
3. **Capacity Check**: Filter checks if current requests < `maxRequests`
335
4. **Immediate Processing**: If capacity available, request proceeds immediately
336
5. **Wait Period**: If no capacity, request waits for `waitMs` milliseconds
337
6. **Suspension**: After wait period, request is suspended for up to `suspendMs`
338
7. **Queue Management**: Suspended requests are queued by priority
339
8. **Resume Processing**: When capacity becomes available, highest priority request is resumed
340

341
### Priority-Based Queuing
342

343
Requests are queued in priority order when server capacity is exceeded:
344
- Higher priority numbers = higher precedence
345
- Equal priority requests are processed in FIFO order
346
- Priority range: 1 to `maxPriority` (default 1-10)
347

348
## JMX Management
349

350
When `managedAttr` is enabled, the filter exposes JMX management capabilities:
351

352
```java
353
// Access QoS metrics via ServletContext
354
QoSFilter qosFilter = (QoSFilter) servletContext.getAttribute("QoSFilter");
355

356
// Get current configuration
357
int maxRequests = qosFilter.getMaxRequests();
358
long waitTime = qosFilter.getWaitMs();
359
long suspendTime = qosFilter.getSuspendMs();
360

361
// Monitor current state (implementation-dependent)
362
// Actual metrics depend on JMX integration
363
```
364

365
## Performance Considerations
366

367
### Capacity Planning
368
- Set `maxRequests` based on server resources and expected load
369
- Consider memory usage: each suspended request consumes resources
370
- Monitor queue lengths and suspension times
371

372
### Wait vs Suspend Times
373
- `waitMs`: Short wait before suspension (reduces unnecessary suspensions)
374
- `suspendMs`: Maximum time a request can be suspended (prevents indefinite waits)
375
- Balance between responsiveness and resource utilization
376

377
### Priority Strategy
378
- Use priorities sparingly - too many levels can complicate management
379
- Base priorities on business logic rather than technical metrics
380
- Consider the impact of priority inversions
381

382
## Migration Guide
383

384
Since QoSFilter is deprecated, consider migrating to `org.eclipse.jetty.server.handler.QoSHandler`:
385

386
```java
387
// Old approach (deprecated)
388
QoSFilter filter = new QoSFilter();
389

390
// New approach (recommended)  
391
QoSHandler handler = new QoSHandler();
392
handler.setMaxRequestCount(25);
393
handler.setMaxSuspendTime(30000);
394
```
395

396
The new handler provides:
397
- Better integration with Jetty's async processing
398
- Improved performance and resource management
399
- More flexible configuration options
400
- Better monitoring and management capabilities
401

402
## Common Use Cases
403

404
### API Rate Limiting
405
Prevent API overload by limiting concurrent requests per endpoint.
406

407
### Resource Protection
408
Protect database connections and expensive operations from overwhelming traffic.
409

410
### User Experience
411
Maintain responsive user interfaces by prioritizing interactive requests over batch operations.
412

413
### System Stability
414
Prevent server crashes due to resource exhaustion during traffic spikes.