0
# URL Operations
1

2
URL creation, parsing, encoding, and manipulation utilities through the URLUtil class.
3

4
## Capabilities
5

6
### URL Creation and Conversion
7

8
Create URL objects from various sources and convert between URL types.
9

10
```java { .api }
11
/**
12
 * Create URL from string
13
 * @param url URL string
14
 * @return URL object
15
 */
16
public static URL url(String url);
17

18
/**
19
 * Create URL from URI
20
 * @param uri URI object
21
 * @return URL object
22
 */
23
public static URL url(URI uri);
24

25
/**
26
 * Create URL with custom stream handler
27
 * @param url URL string
28
 * @param handler custom URL stream handler
29
 * @return URL object
30
 */
31
public static URL url(String url, URLStreamHandler handler);
32

33
/**
34
 * Convert URL string to HTTP URL (add http:// if missing)
35
 * @param urlStr URL string
36
 * @return URL object with HTTP protocol
37
 */
38
public static URL toUrlForHttp(String urlStr);
39

40
/**
41
 * Convert URL to URI
42
 * @param url URL object
43
 * @return URI object
44
 */
45
public static URI toURI(URL url);
46

47
/**
48
 * Convert URL to URI with encoding control
49
 * @param url URL object
50
 * @param isEncode whether to encode the URL
51
 * @return URI object
52
 */
53
public static URI toURI(URL url, boolean isEncode);
54
```
55

56
**Usage Examples:**
57

58
```java
59
import cn.hutool.core.util.URLUtil;
60
import java.net.URL;
61
import java.net.URI;
62

63
// Create URLs
64
URL httpUrl = URLUtil.url("https://example.com/path");
65
URL fileUrl = URLUtil.url("file:///home/user/file.txt");
66

67
// Auto-add HTTP protocol
68
URL autoHttp = URLUtil.toUrlForHttp("example.com/page"); // becomes http://example.com/page
69

70
// URL to URI conversion
71
URI uri = URLUtil.toURI(httpUrl);
72
```
73

74
### URL Encoding and Decoding
75

76
Handle URL encoding and decoding with proper character handling.
77

78
```java { .api }
79
/**
80
 * Decode URL string
81
 * @param url encoded URL string
82
 * @return decoded URL string
83
 */
84
public static String decode(String url);
85

86
/**
87
 * Encode blank spaces in URL
88
 * @param urlStr URL string with spaces
89
 * @return URL string with encoded spaces
90
 */
91
public static String encodeBlank(CharSequence urlStr);
92

93
/**
94
 * Get decoded path from URL
95
 * @param url URL object
96
 * @return decoded path component
97
 */
98
public static String getDecodedPath(URL url);
99

100
/**
101
 * Get path from URI string
102
 * @param uriStr URI string
103
 * @return path component
104
 */
105
public static String getPath(String uriStr);
106
```
107

108
**Usage Examples:**
109

110
```java
111
import cn.hutool.core.util.URLUtil;
112
import java.net.URL;
113

114
// URL encoding/decoding
115
String encoded = URLUtil.encodeBlank("https://example.com/path with spaces");
116
String decoded = URLUtil.decode("https://example.com/path%20with%20spaces");
117

118
// Path extraction
119
URL url = URLUtil.url("https://example.com/user/profile?id=123");
120
String path = URLUtil.getDecodedPath(url); // "/user/profile"
121
String pathFromUri = URLUtil.getPath("https://example.com/api/users"); // "/api/users"
122
```
123

124
### URL Normalization and Validation
125

126
Normalize URL formats and validate URL types.
127

128
```java { .api }
129
/**
130
 * Normalize URL string
131
 * @param url URL string to normalize
132
 * @return normalized URL string
133
 */
134
public static String normalize(String url);
135

136
/**
137
 * Normalize URL with path encoding control
138
 * @param url URL string to normalize
139
 * @param isEncodePath whether to encode path components
140
 * @return normalized URL string
141
 */
142
public static String normalize(String url, boolean isEncodePath);
143

144
/**
145
 * Normalize URL with full control
146
 * @param url URL string to normalize
147
 * @param isEncodePath whether to encode path components
148
 * @param replaceSlash whether to replace backslashes with forward slashes
149
 * @return normalized URL string
150
 */
151
public static String normalize(String url, boolean isEncodePath, boolean replaceSlash);
152

153
/**
154
 * Check if URL is a file URL
155
 * @param url URL to check
156
 * @return true if URL uses file protocol
157
 */
158
public static boolean isFileURL(URL url);
159

160
/**
161
 * Check if URL is a JAR URL
162
 * @param url URL to check
163
 * @return true if URL points to JAR content
164
 */
165
public static boolean isJarURL(URL url);
166

167
/**
168
 * Check if URL is a JAR file URL
169
 * @param url URL to check
170
 * @return true if URL points to JAR file
171
 */
172
public static boolean isJarFileURL(URL url);
173
```
174

175
**Usage Examples:**
176

177
```java
178
import cn.hutool.core.util.URLUtil;
179
import java.net.URL;
180

181
// URL normalization
182
String messy = "http://example.com//path/../other/./file.html";
183
String clean = URLUtil.normalize(messy); // "http://example.com/other/file.html"
184

185
String withBackslashes = "http://example.com\\path\\file.html";
186
String normalized = URLUtil.normalize(withBackslashes, false, true); // "http://example.com/path/file.html"
187

188
// URL type checking
189
URL fileUrl = URLUtil.url("file:///home/user/file.txt");
190
URL jarUrl = URLUtil.url("jar:file:/app.jar!/config.properties");
191

192
boolean isFile = URLUtil.isFileURL(fileUrl); // true
193
boolean isJar = URLUtil.isJarURL(jarUrl); // true
194
```
195

196
### URL Content Access
197

198
Access content from URLs and handle different URL types.
199

200
```java { .api }
201
/**
202
 * Get input stream from URL
203
 * @param url URL to read from
204
 * @return InputStream for URL content
205
 */
206
public static InputStream getStream(URL url);
207

208
/**
209
 * Get buffered reader from URL
210
 * @param url URL to read from
211
 * @param charset character encoding
212
 * @return BufferedReader for URL content
213
 */
214
public static BufferedReader getReader(URL url, Charset charset);
215

216
/**
217
 * Get JAR file from JAR URL
218
 * @param url JAR URL
219
 * @return JarFile object
220
 */
221
public static JarFile getJarFile(URL url);
222

223
/**
224
 * Get connection from URL
225
 * @param url URL to connect to
226
 * @return URLConnection object
227
 */
228
public static URLConnection getConnection(URL url);
229
```
230

231
**Usage Examples:**
232

233
```java
234
import cn.hutool.core.util.URLUtil;
235
import java.io.InputStream;
236
import java.io.BufferedReader;
237
import java.net.URL;
238
import java.nio.charset.StandardCharsets;
239
import java.util.jar.JarFile;
240

241
// Read from URL
242
URL configUrl = URLUtil.url("https://example.com/config.json");
243
try (InputStream stream = URLUtil.getStream(configUrl)) {
244
    // Process stream content
245
}
246

247
// Read text from URL
248
URL textUrl = URLUtil.url("https://example.com/data.txt");
249
try (BufferedReader reader = URLUtil.getReader(textUrl, StandardCharsets.UTF_8)) {
250
    String line = reader.readLine();
251
}
252

253
// Access JAR file
254
URL jarUrl = URLUtil.url("jar:file:/app.jar!/");
255
JarFile jarFile = URLUtil.getJarFile(jarUrl);
256
```
257

258
### URL Host and Component Extraction
259

260
Extract components from URLs and manipulate URL parts.
261

262
```java { .api }
263
/**
264
 * Get host URI from URL
265
 * @param url URL to extract host from
266
 * @return URI with host information only
267
 */
268
public static URI getHost(URL url);
269

270
/**
271
 * Build query string from parameters
272
 * @param params parameter map
273
 * @param charset character encoding
274
 * @return query string
275
 */
276
public static String buildQuery(Map<String, Object> params, Charset charset);
277

278
/**
279
 * Parse query string to map
280
 * @param query query string to parse
281
 * @param charset character encoding
282
 * @return map of query parameters
283
 */
284
public static Map<String, String> parseQuery(String query, Charset charset);
285
```
286

287
**Usage Examples:**
288

289
```java
290
import cn.hutool.core.util.URLUtil;
291
import java.net.URL;
292
import java.net.URI;
293
import java.nio.charset.StandardCharsets;
294
import java.util.Map;
295
import java.util.HashMap;
296

297
// Extract host
298
URL fullUrl = URLUtil.url("https://api.example.com:8443/v1/users?page=1");
299
URI hostUri = URLUtil.getHost(fullUrl); // https://api.example.com:8443
300

301
// Query string operations
302
Map<String, Object> params = new HashMap<>();
303
params.put("page", 1);
304
params.put("size", 10);
305
params.put("search", "john doe");
306

307
String queryString = URLUtil.buildQuery(params, StandardCharsets.UTF_8);
308
// Result: "page=1&size=10&search=john+doe"
309

310
Map<String, String> parsed = URLUtil.parseQuery(queryString, StandardCharsets.UTF_8);
311
// Result: {"page": "1", "size": "10", "search": "john doe"}
312
```
313

314
## Common Types
315

316
```java { .api }
317
// URL and networking types
318
import java.net.URL;
319
import java.net.URI;
320
import java.net.URLConnection;
321
import java.net.URLStreamHandler;
322
import java.net.HttpURLConnection;
323
import java.net.JarURLConnection;
324
import java.util.jar.JarFile;
325
import java.nio.charset.Charset;
326

327
// URL protocol constants
328
public static final String CLASSPATH_URL_PREFIX = "classpath:";
329
public static final String FILE_URL_PREFIX = "file:";
330
public static final String JAR_URL_PREFIX = "jar:";
331
public static final String WAR_URL_PREFIX = "war:";
332
public static final String URL_PROTOCOL_FILE = "file";
333
public static final String URL_PROTOCOL_JAR = "jar";
334
public static final String URL_PROTOCOL_WAR = "war";
335
public static final String URL_PROTOCOL_ZIP = "zip";
336
```