0
# URI Processing
1

2
Comprehensive URI parsing, validation, and manipulation with compliance checking, efficient immutable/mutable patterns, and violation tracking.
3

4
## Capabilities
5

6
### HttpURI Interface
7

8
Core URI interface with parsing, validation, and component access.
9

10
```java { .api }
11
/**
12
 * HTTP URI interface with immutable and mutable implementations
13
 */
14
interface HttpURI {
15
    /** Get URI scheme (http, https, ws, wss) */
16
    String getScheme();
17
    
18
    /** Get host component */
19
    String getHost();
20
    
21
    /** Get port number (-1 if not specified) */
22
    int getPort();
23
    
24
    /** Get authority component (host:port) */
25
    String getAuthority();
26
    
27
    /** Get user info component */
28
    String getUser();
29
    
30
    /** Get raw path component */
31
    String getPath();
32
    
33
    /** Get normalized/canonical path */
34
    String getCanonicalPath();
35
    
36
    /** Get URL-decoded path */
37
    String getDecodedPath();
38
    
39
    /** Get last path parameter */
40
    String getParam();
41
    
42
    /** Get path with query string */
43
    String getPathQuery();
44
    
45
    /** Get query string component */
46
    String getQuery();
47
    
48
    /** Get fragment component */
49
    String getFragment();
50
    
51
    /** Check if URI is absolute (has scheme) */
52
    boolean isAbsolute();
53
    
54
    /** Check if URI has authority component */
55
    boolean hasAuthority();
56
    
57
    /** Check if URI has compliance violations */
58
    boolean isAmbiguous();
59
    
60
    /** Get detected compliance violations */
61
    Set<UriCompliance.Violation> getViolations();
62
    
63
    /** Convert to immutable URI */
64
    Immutable asImmutable();
65
    
66
    /** Get complete URI as string */
67
    String asString();
68
    
69
    /** Create mutable URI builder */
70
    static Mutable build();
71
    
72
    /** Parse URI string to mutable builder */
73
    static Mutable build(String uri);
74
    
75
    /** Parse URI string to immutable URI */
76
    static Immutable from(String uri);
77
    
78
    /** Convert java.net.URI to immutable URI */
79
    static Immutable from(URI uri);
80
    
81
    /** Build URI from components */
82
    static Immutable from(String scheme, String host, int port, String pathQuery);
83
    
84
    /**
85
     * Immutable URI implementation
86
     */
87
    interface Immutable extends HttpURI {
88
        /** Convert to mutable builder */
89
        Mutable mutable();
90
    }
91
    
92
    /**
93
     * Mutable URI builder
94
     */
95
    interface Mutable extends HttpURI {
96
        /** Set URI scheme */
97
        Mutable scheme(String scheme);
98
        
99
        /** Set user info */
100
        Mutable user(String user);
101
        
102
        /** Set host */
103
        Mutable host(String host);
104
        
105
        /** Set port */
106
        Mutable port(int port);
107
        
108
        /** Set authority (host:port) */
109
        Mutable authority(String authority);
110
        
111
        /** Set path component */
112
        Mutable path(String path);
113
        
114
        /** Set path parameter */
115
        Mutable param(String param);
116
        
117
        /** Set query string */
118
        Mutable query(String query);
119
        
120
        /** Set fragment */
121
        Mutable fragment(String fragment);
122
        
123
        /** Set complete URI from string */
124
        Mutable uri(String uri);
125
        
126
        /** Set complete URI from java.net.URI */
127
        Mutable uri(URI uri);
128
        
129
        /** Build immutable URI */
130
        Immutable asImmutable();
131
        
132
        /** Clear all components */
133
        void clear();
134
    }
135
}
136
```
137

138
### UriCompliance Class
139

140
URI compliance modes and violation handling.
141

142
```java { .api }
143
/**
144
 * URI compliance modes and validation
145
 */
146
class UriCompliance {
147
    /** Default strict compliance */
148
    static final UriCompliance DEFAULT;
149
    
150
    /** Legacy compatibility mode */
151
    static final UriCompliance LEGACY;
152
    
153
    /** Unsafe character mode (allows more characters) */
154
    static final UriCompliance UNSAFE;
155
    
156
    /** Check if violation is allowed in this compliance mode */
157
    boolean allows(Violation violation);
158
    
159
    /** Get set of allowed violations */
160
    Set<Violation> getAllowed();
161
    
162
    /** Get compliance mode name */
163
    String getName();
164
    
165
    /**
166
     * URI compliance violations
167
     */
168
    enum Violation {
169
        /** Ambiguous path separator */
170
        AMBIGUOUS_PATH_SEPARATOR,
171
        
172
        /** Ambiguous path segment */
173
        AMBIGUOUS_PATH_SEGMENT,
174
        
175
        /** Ambiguous path parameter */
176
        AMBIGUOUS_PATH_PARAMETER,
177
        
178
        /** Ambiguous empty segment */
179
        AMBIGUOUS_EMPTY_SEGMENT,
180
        
181
        /** UTF-8 not preferred encoding */
182
        UTF8_NOT_PREFERRED,
183
        
184
        /** Non-canonical ambiguous URI */
185
        NON_CANONICAL_AMBIGUOUS_URI,
186
        
187
        /** Suspicious path characters */
188
        SUSPICIOUS_PATH_CHARACTERS;
189
    }
190
}
191
```
192

193
### HttpScheme Enumeration
194

195
HTTP URI scheme handling with default ports.
196

197
```java { .api }
198
/**
199
 * HTTP URI schemes with default port handling
200
 */
201
enum HttpScheme {
202
    /** HTTP scheme */
203
    HTTP("http", 80),
204
    
205
    /** HTTPS scheme */
206
    HTTPS("https", 443),
207
    
208
    /** WebSocket scheme */
209
    WS("ws", 80),
210
    
211
    /** Secure WebSocket scheme */
212
    WSS("wss", 443);
213
    
214
    /** Get scheme as string */
215
    String asString();
216
    
217
    /** Get default port for scheme */
218
    int getDefaultPort();
219
    
220
    /** Check if scheme matches string (case insensitive) */
221
    boolean is(String scheme);
222
}
223
```
224

225
**Usage Examples:**
226

227
```java
228
import org.eclipse.jetty.http.*;
229
import java.net.URI;
230

231
// Parse URI from string
232
HttpURI.Immutable uri = HttpURI.from("https://example.com:8443/api/users?id=123&active=true#section1");
233

234
// Access URI components
235
String scheme = uri.getScheme();        // "https"
236
String host = uri.getHost();            // "example.com"
237
int port = uri.getPort();               // 8443
238
String authority = uri.getAuthority();   // "example.com:8443"
239
String path = uri.getPath();            // "/api/users"
240
String query = uri.getQuery();          // "id=123&active=true"
241
String fragment = uri.getFragment();    // "section1"
242

243
// Check URI properties
244
boolean absolute = uri.isAbsolute();    // true
245
boolean hasAuth = uri.hasAuthority();   // true
246

247
// Build URI with mutable builder
248
HttpURI.Mutable builder = HttpURI.build()
249
    .scheme("https")
250
    .host("api.example.com")
251
    .port(443)
252
    .path("/v1/users")
253
    .query("limit=10&offset=20");
254

255
HttpURI.Immutable builtUri = builder.asImmutable();
256
String uriString = builtUri.asString(); // "https://api.example.com/v1/users?limit=10&offset=20"
257

258
// Parse with validation
259
HttpURI.Immutable parsedUri = HttpURI.from("/path/with spaces/file.txt");
260
boolean hasViolations = parsedUri.isAmbiguous();
261
Set<UriCompliance.Violation> violations = parsedUri.getViolations();
262

263
// Modify existing URI
264
HttpURI.Mutable modified = uri.mutable()
265
    .path("/api/products")
266
    .query("category=electronics")
267
    .fragment(null);
268

269
// URI normalization and decoding
270
String canonical = uri.getCanonicalPath();  // Normalized path
271
String decoded = uri.getDecodedPath();      // URL-decoded path
272

273
// Convert from java.net.URI
274
URI javaUri = new URI("http://localhost:8080/app");
275
HttpURI.Immutable jettyUri = HttpURI.from(javaUri);
276

277
// Build from components
278
HttpURI.Immutable componentUri = HttpURI.from("http", "localhost", 8080, "/api/status");
279

280
// Working with compliance modes
281
UriCompliance strict = UriCompliance.DEFAULT;
282
UriCompliance lenient = UriCompliance.LEGACY;
283

284
boolean allowsSpaces = lenient.allows(UriCompliance.Violation.SUSPICIOUS_PATH_CHARACTERS);
285

286
// Check URI schemes
287
HttpScheme httpScheme = HttpScheme.HTTP;
288
int defaultPort = httpScheme.getDefaultPort(); // 80
289
boolean isHttps = HttpScheme.HTTPS.is("HTTPS"); // true (case insensitive)
290

291
// Path parameter handling
292
HttpURI.Immutable pathParamUri = HttpURI.from("/users;id=123/profile;edit=true");
293
String lastParam = pathParamUri.getParam(); // "edit=true"
294

295
// URI with user info
296
HttpURI.Immutable userUri = HttpURI.from("ftp://user:pass@ftp.example.com/files");
297
String userInfo = userUri.getUser(); // "user:pass"
298
```