Parsing URLs
suggest changeA URL packs several pieces of information into one string:
https://alice:s3cret@api.example.com:8443/v1/items?q=java&page=2#reviews
\___/ \__________/ \_____________/ \__/\_______/ \____________/ \_____/
scheme user info host port path query fragment
\_______________________________/
authority
The JDK class for taking such a string apart is java.net.URI. It parses according to RFC 2396 (with a few RFC 3986 extensions such as IPv6 hosts), gives you each component in both raw (percent-encoded) and decoded form, resolves relative links and builds new URIs. It never touches the network.
This article covers parsing and validating URLs, reading query parameters, encoding values correctly when building URLs, resolving relative references, and converting between URI, URL and Path. Each example is a single file you can run with java Example.java. All output comes from JDK 25 (run with -Dstdout.encoding=UTF-8 so non-ASCII characters print correctly on Windows).
See HttpURLConnection and REST APIs for actually fetching URLs, and A minimal HTTP server for handling request URIs on the server side.
URI, not URL
Java has two classes, and for parsing you want URI:
java.net.URIis a pure value: it parses and validates syntax, has raw and decoded getters, supports any scheme (redis:,mailto:,urn:), and itsequals()compares text.java.net.URLis tied to protocol handlers for fetching. Its constructors don't validate much (spaces are accepted), it only accepts schemes the JDK has a handler for, andURL.equals()andhashCode()resolve the host name through DNS, which makes them slow, network-dependent and wrong for virtual hosts. AllURLconstructors are deprecated since JDK 20.
Parse with URI, and call uri.toURL() only when an old API insists on a URL. java.net.http.HttpClient takes a URI directly.
Getting the parts
URI.create() parses a string and throws an unchecked IllegalArgumentException if it's invalid. Use it for literals you know are correct. For input from users, files or other systems use new URI(String), which throws the checked URISyntaxException (covered below).
import java.net.URI;
public class Parts {
public static void main(String[] args) {
URI uri = URI.create(
"https://alice:s3cret@api.example.com:8443/v1/search%20results/items?q=java+url&tag=a%26b#page-2");
System.out.println("scheme: " + uri.getScheme());
System.out.println("authority: " + uri.getAuthority());
System.out.println("userInfo: " + uri.getUserInfo());
System.out.println("host: " + uri.getHost());
System.out.println("port: " + uri.getPort());
System.out.println("path: " + uri.getPath());
System.out.println("rawPath: " + uri.getRawPath());
System.out.println("query: " + uri.getQuery());
System.out.println("rawQuery: " + uri.getRawQuery());
System.out.println("fragment: " + uri.getFragment());
System.out.println("absolute: " + uri.isAbsolute());
System.out.println("opaque: " + uri.isOpaque());
}
}
Output:
scheme: https
authority: alice:s3cret@api.example.com:8443
userInfo: alice:s3cret
host: api.example.com
port: 8443
path: /v1/search results/items
rawPath: /v1/search%20results/items
query: q=java+url&tag=a&b
rawQuery: q=java+url&tag=a%26b
fragment: page-2
absolute: true
opaque: false
Things to note:
- Most components have two getters.
getRawPath(),getRawQuery(),getRawUserInfo(),getRawFragment()andgetRawAuthority()return the text exactly as it appears. The plain getters decode%XXsequences. - The decoded query is useless for parsing:
tag=a%26bbecametag=a&b, so you can no longer tell the encoded&from a separator. Always splitgetRawQuery()and decode each piece yourself (next section). getQuery()doesn't turn+into a space.+meaning space is a convention of HTML forms (application/x-www-form-urlencoded), not of URIs in general.- A missing component is
nulland a missing port is-1. Keep that in mind before calling methods on the results. - The scheme is returned as written. Compare schemes and hosts with
equalsIgnoreCase()or lowercase them withLocale.ROOTfirst.
The default port
getPort() returns -1 when the URL doesn't spell out a port. If you need the port to connect to, fill in the scheme's default yourself:
import java.net.URI;
public class Port {
static int effectivePort(URI uri) {
if (uri.getPort() != -1) return uri.getPort();
return switch (uri.getScheme().toLowerCase()) {
case "http", "ws" -> 80;
case "https", "wss" -> 443;
case "ftp" -> 21;
default -> throw new IllegalArgumentException("no default port for " + uri.getScheme());
};
}
public static void main(String[] args) {
for (String s : new String[] {"https://example.com/", "http://example.com:8080/", "WSS://example.com/chat"}) {
URI uri = URI.create(s);
System.out.println(s + " -> getPort()=" + uri.getPort() + ", effective=" + effectivePort(uri));
}
}
}
Output:
https://example.com/ -> getPort()=-1, effective=443
http://example.com:8080/ -> getPort()=8080, effective=8080
WSS://example.com/chat -> getPort()=-1, effective=443
Invalid input
new URI(String) throws URISyntaxException for strings that aren't valid URIs. The exception tells you what's wrong and where:
import java.net.URI;
import java.net.URISyntaxException;
import java.util.Optional;
public class Invalid {
static Optional<URI> tryParse(String s) {
try {
return Optional.of(new URI(s));
} catch (URISyntaxException e) {
System.out.println(" error: " + e.getMessage());
System.out.println(" reason=" + e.getReason() + ", index=" + e.getIndex());
return Optional.empty();
}
}
public static void main(String[] args) {
String[] inputs = {
"https://example.com/a path",
"https://example.com/?q={x}",
"https://exa mple.com/",
"http://[::1/",
"https://example.com:99999/",
"https://example.com/ok",
};
for (String s : inputs) {
System.out.println(s);
tryParse(s).ifPresent(u -> System.out.println(" ok, host=" + u.getHost() + ", port=" + u.getPort()));
}
try {
URI.create("https://example.com/a path");
} catch (IllegalArgumentException e) {
System.out.println("URI.create threw " + e.getClass().getSimpleName()
+ ", cause: " + e.getCause().getClass().getSimpleName());
}
}
}
Output:
https://example.com/a path
error: Illegal character in path at index 21: https://example.com/a path
reason=Illegal character in path, index=21
https://example.com/?q={x}
error: Illegal character in query at index 23: https://example.com/?q={x}
reason=Illegal character in query, index=23
https://exa mple.com/
error: Illegal character in authority at index 11: https://exa mple.com/
reason=Illegal character in authority, index=11
http://[::1/
error: Expected closing bracket for IPv6 address at index 11: http://[::1/
reason=Expected closing bracket for IPv6 address, index=11
https://example.com:99999/
ok, host=example.com, port=99999
https://example.com/ok
ok, host=example.com, port=-1
URI.create threw IllegalArgumentException, cause: URISyntaxException
Spaces, {, }, ", <, >, \, | and ^ aren't allowed anywhere in a URI. They must be percent-encoded (%20 and so on). Browsers are forgiving and fix such URLs silently, so URLs copied from a browser's address bar or typed by people often fail to parse. Encode the parts properly when you build the URL (see Building URLs below) instead of trying to repair a whole URL string afterwards.
Note that port 99999 was accepted. The parser only checks that the port is made of digits. Validate the range yourself if it matters.
A URI can parse without a host
Many strings that don't look like URLs are still valid URIs, and the parser falls back to a less specific interpretation instead of failing:
import java.net.URI;
public class Gotchas {
static void show(String s) {
URI u = URI.create(s);
System.out.printf("%-32s scheme=%s host=%s authority=%s path=%s ssp=%s%n",
s, u.getScheme(), u.getHost(), u.getAuthority(), u.getPath(), u.getSchemeSpecificPart());
}
public static void main(String[] args) {
show("https://my_server.local/x");
show("example.com/path");
show("//example.com/path");
show("mailto:alice@example.com");
show("localhost:8080");
show("https://example.com");
show("https://[2001:db8::1]:8443/");
}
}
Output:
https://my_server.local/x scheme=https host=null authority=my_server.local path=/x ssp=//my_server.local/x
example.com/path scheme=null host=null authority=null path=example.com/path ssp=example.com/path
//example.com/path scheme=null host=example.com authority=example.com path=/path ssp=//example.com/path
mailto:alice@example.com scheme=mailto host=null authority=null path=null ssp=alice@example.com
localhost:8080 scheme=localhost host=null authority=null path=null ssp=8080
https://example.com scheme=https host=example.com authority=example.com path= ssp=//example.com
https://[2001:db8::1]:8443/ scheme=https host=[2001:db8::1] authority=[2001:db8::1]:8443 path=/ ssp=//[2001:db8::1]:8443/
my_server.localhas an underscore, which isn't legal in a host name. The parser doesn't fail. It treats the authority as a registry-based authority andgetHost()returnsnull. Code that doesuri.getHost().toLowerCase()then throws aNullPointerException.example.com/pathhas no scheme, so it's a relative reference: everything is the path. People often type URLs this way.localhost:8080parses as schemelocalhostwith an opaque part8080. The same happens withhost:portstrings in configuration files.mailto:alice@example.comis an opaque URI: no//after the scheme, so there's no host or path, only a scheme-specific part.https://example.comhas an empty path, not/.- IPv6 hosts keep their brackets in
getHost().
When you need a real server-based authority, call parseServerAuthority(). It reparses the authority strictly and throws when it's not a valid [user@]host[:port]:
import java.net.URI;
import java.net.URISyntaxException;
public class Strict {
public static void main(String[] args) {
for (String s : new String[] {"https://my_server.local/x", "https://example.com:8443/", "https://user@:80/"}) {
try {
URI u = new URI(s).parseServerAuthority();
System.out.println(s + " -> host=" + u.getHost() + ", port=" + u.getPort());
} catch (URISyntaxException e) {
System.out.println(s + " -> " + e.getMessage());
}
}
}
}
Output:
https://my_server.local/x -> Illegal character in hostname at index 10: https://my_server.local/x
https://example.com:8443/ -> host=example.com, port=8443
https://user@:80/ -> Expected hostname at index 13: https://user@:80/
Parsing the query string
The JDK has no query string parser, but it takes a dozen lines. Split the raw query on &, split each pair on the first =, and decode both sides with URLDecoder. A key can appear more than once (tag=hot&tag=sweet), so collect values into a list:
import java.net.URI;
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
public class Query {
static Map<String, List<String>> parseQuery(String rawQuery) {
Map<String, List<String>> params = new LinkedHashMap<>();
if (rawQuery == null || rawQuery.isEmpty()) return params;
for (String pair : rawQuery.split("&")) {
if (pair.isEmpty()) continue; // "a=1&&b=2"
int eq = pair.indexOf('=');
String key = eq < 0 ? pair : pair.substring(0, eq);
String value = eq < 0 ? "" : pair.substring(eq + 1);
params.computeIfAbsent(decode(key), k -> new ArrayList<>()).add(decode(value));
}
return params;
}
static String decode(String s) {
return URLDecoder.decode(s, StandardCharsets.UTF_8);
}
public static void main(String[] args) {
URI uri = URI.create(
"https://shop.example.com/search?q=caf%C3%A9+au+lait&tag=hot&tag=sweet¬e=a%26b%3Dc&debug&&empty=");
Map<String, List<String>> params = parseQuery(uri.getRawQuery());
params.forEach((k, v) -> System.out.println(k + " -> " + v.stream().map(s -> "\"" + s + "\"").toList()));
String q = params.getOrDefault("q", List.of()).stream().findFirst().orElse("");
int page = Integer.parseInt(params.getOrDefault("page", List.of("1")).getFirst());
System.out.println("q=" + q + ", page=" + page);
System.out.println("getQuery() would give: " + uri.getQuery());
}
}
Output:
q -> ["café au lait"]
tag -> ["hot", "sweet"]
note -> ["a&b=c"]
debug -> [""]
empty -> [""]
q=café au lait, page=1
getQuery() would give: q=café+au+lait&tag=hot&tag=sweet¬e=a&b=c&debug&&empty=
- Split the raw query, then decode. Decoding first breaks values containing
%26(&) or%3D(=), as the last line shows. URLDecoderuses form encoding rules, so+becomes a space. That's what browsers send for forms and what most servers expect in query strings. Always passStandardCharsets.UTF_8.- A key without
=(debug) gets an empty value, and empty pairs (&&) are skipped. Whetherdebugmeans "true" is up to your application. LinkedHashMapkeeps the parameters in their original order, which helps with logging and signing.- The same function parses
application/x-www-form-urlencodedrequest bodies, because they use the same format.
URLDecoder throws IllegalArgumentException for malformed escapes, and silently replaces invalid UTF-8 with U+FFFD. Since the query comes from outside, catch the exception and answer with a 400 error instead of letting it crash the request:
import java.net.URLDecoder;
import java.nio.charset.StandardCharsets;
public class BadPercent {
public static void main(String[] args) {
for (String s : new String[] {"100%25", "100%", "%zz", "%C3"}) {
try {
System.out.println(s + " -> " + URLDecoder.decode(s, StandardCharsets.UTF_8));
} catch (IllegalArgumentException e) {
System.out.println(s + " -> " + e.getMessage());
}
}
}
}
Output:
100%25 -> 100%
100% -> URLDecoder: Incomplete trailing escape (%) pattern
%zz -> URLDecoder: Illegal hex characters in escape (%) pattern - not a hexadecimal digit: "z" = 122
%C3 -> �
Building URLs
When you put values into a URL, encode each value separately, then join the parts. URLEncoder.encode(value, StandardCharsets.UTF_8) encodes everything except letters, digits and .-*_, which is right for query parameter names and values. It produces form encoding, so a space becomes +. In a path a + is a literal plus sign, so for path segments replace + with %20:
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URLDecoder;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.stream.Collectors;
public class Build {
static String encode(String s) {
return URLEncoder.encode(s, StandardCharsets.UTF_8);
}
static String encodePathSegment(String s) {
// URLEncoder is for form data: it turns ' ' into '+', which is wrong in a path
return URLEncoder.encode(s, StandardCharsets.UTF_8).replace("+", "%20");
}
static String queryString(Map<String, String> params) {
return params.entrySet().stream()
.map(e -> encode(e.getKey()) + "=" + encode(e.getValue()))
.collect(Collectors.joining("&"));
}
public static void main(String[] args) throws URISyntaxException {
Map<String, String> params = new LinkedHashMap<>();
params.put("q", "café & croissants");
params.put("redirect", "https://example.com/done?x=1");
params.put("sort", "price asc");
String file = "Q3 report/final.pdf";
URI uri = URI.create("https://api.example.com/v1/files/"
+ encodePathSegment(file) + "?" + queryString(params));
System.out.println(uri);
// getPath() decodes %2F into '/', so the segment boundary is lost
System.out.println("getPath(): " + uri.getPath());
// Split the raw path first, then decode each segment
String[] segments = Arrays.stream(uri.getRawPath().split("/"))
.map(s -> URLDecoder.decode(s.replace("+", "%2B"), StandardCharsets.UTF_8))
.toArray(String[]::new);
System.out.println("last segment: " + segments[segments.length - 1]);
// The multi-argument constructors quote illegal characters for you...
URI quoted = new URI("https", "api.example.com", "/v1/files/Q3 report.pdf", "q=a b", null);
System.out.println(quoted);
// ...but leave legal ones such as '&', '=' and '/' alone
URI ambiguous = new URI("https", "api.example.com", "/search", "q=salt & pepper", null);
System.out.println(ambiguous);
// Non-ASCII characters are kept as is; toASCIIString() encodes them
URI unicode = new URI("https", "example.com", "/menü", null);
System.out.println(unicode + " | " + unicode.toASCIIString());
}
}
Output:
https://api.example.com/v1/files/Q3%20report%2Ffinal.pdf?q=caf%C3%A9+%26+croissants&redirect=https%3A%2F%2Fexample.com%2Fdone%3Fx%3D1&sort=price+asc
getPath(): /v1/files/Q3 report/final.pdf
last segment: Q3 report/final.pdf
https://api.example.com/v1/files/Q3%20report.pdf?q=a%20b
https://api.example.com/search?q=salt%20&%20pepper
https://example.com/menü | https://example.com/men%C3%BC
- The
redirectvalue is itself a URL. Encoded properly, its?,=and/can't be confused with the outer URL's structure. - The file name contains
/, whichencodePathSegment()turns into%2F, so the server sees one segment.getPath()decodes it back to/and the boundary disappears. To read segments, splitgetRawPath()on/and decode each part. Thereplace("+", "%2B")keeps a literal+in the path from being decoded into a space byURLDecoder. - The multi-argument constructors, such as
new URI(scheme, host, path, fragment)andnew URI(scheme, authority, path, query, fragment), quote characters that are illegal, soQ3 report.pdfworks. They leave characters that are legal but meaningful alone, soq=salt & pepperproduces a query with two parameters,q=saltandpepper. Use them to assemble already encoded query strings, not raw values. - The constructors also keep non-ASCII characters (
menü) unencoded, whichURIallows as "other" characters. UsetoASCIIString()when the URI goes into an HTTP request line or a header.
Changing one part
URI is immutable and has no withQuery() style methods. Rebuild the string from the raw parts so nothing gets decoded and re-encoded on the way:
import java.net.URI;
import java.net.URISyntaxException;
public class Modify {
// Builds a URI from raw (already encoded) parts, so nothing is decoded and re-encoded
static URI withRawQuery(URI u, String rawQuery) {
StringBuilder sb = new StringBuilder();
if (u.getScheme() != null) sb.append(u.getScheme()).append(':');
if (u.getRawAuthority() != null) sb.append("//").append(u.getRawAuthority());
sb.append(u.getRawPath());
if (rawQuery != null) sb.append('?').append(rawQuery);
if (u.getRawFragment() != null) sb.append('#').append(u.getRawFragment());
return URI.create(sb.toString());
}
public static void main(String[] args) throws URISyntaxException {
URI u = URI.create("https://example.com/files/a%2Fb.txt?page=1#top");
System.out.println(withRawQuery(u, "page=2&size=50"));
System.out.println(withRawQuery(u, null));
// The 7-argument constructor takes decoded parts, so %2F turns into a real '/'
URI rebuilt = new URI(u.getScheme(), u.getUserInfo(), "cdn.example.com", u.getPort(),
u.getPath(), u.getQuery(), u.getFragment());
System.out.println(rebuilt);
}
}
Output:
https://example.com/files/a%2Fb.txt?page=2&size=50#top
https://example.com/files/a%2Fb.txt#top
https://cdn.example.com/files/a/b.txt?page=1#top
The 7-argument constructor looks convenient for changing the host, but it takes decoded components. Feeding it getPath() turned a%2Fb.txt into two path segments. It's fine for URLs whose parts don't contain encoded reserved characters, but the raw-parts approach always round-trips.
Resolving relative links
Links in HTML pages, Location headers in redirects and paths in API responses are often relative. base.resolve(ref) turns them into absolute URIs:
import java.net.URI;
public class Resolve {
public static void main(String[] args) {
URI base = URI.create("https://example.com/docs/guide/intro.html?lang=en");
String[] refs = {
"setup.html", "./setup.html", "../api/index.html", "/about", "?lang=de",
"#install", "//cdn.example.net/app.js", "https://other.org/x", "",
};
for (String ref : refs) {
System.out.printf("%-28s -> %s%n", "\"" + ref + "\"", base.resolve(ref));
}
URI messy = URI.create("https://example.com/a/./b/../c//d/");
System.out.println("normalize: " + messy.normalize());
URI dir = URI.create("https://example.com/docs/");
URI page = URI.create("https://example.com/docs/guide/intro.html");
System.out.println("relativize: " + dir.relativize(page));
System.out.println("relativize (not under base): "
+ URI.create("https://example.com/docs/guide/").relativize(URI.create("https://example.com/docs/api/x")));
// A base without a trailing slash drops its last segment
URI api = URI.create("https://api.example.com/v2");
System.out.println(api.resolve("users") + " vs " + URI.create("https://api.example.com/v2/").resolve("users"));
}
}
Output:
"setup.html" -> https://example.com/docs/guide/setup.html
"./setup.html" -> https://example.com/docs/guide/setup.html
"../api/index.html" -> https://example.com/docs/api/index.html
"/about" -> https://example.com/about
"?lang=de" -> https://example.com/docs/guide/?lang=de
"#install" -> https://example.com/docs/guide/intro.html?lang=en#install
"//cdn.example.net/app.js" -> https://cdn.example.net/app.js
"https://other.org/x" -> https://other.org/x
"" -> https://example.com/docs/guide/
normalize: https://example.com/a/c/d/
relativize: guide/intro.html
relativize (not under base): https://example.com/docs/api/x
https://api.example.com/users vs https://api.example.com/v2/users
../climbs out of the base's directory, a leading/replaces the whole path,//host/...keeps only the scheme, and an absolute reference replaces everything.URIfollows RFC 2396 for two edge cases where browsers follow RFC 3986:"?lang=de"drops the last path segment (a browser gives/docs/guide/intro.html?lang=de) and""gives the base's directory (a browser gives the base itself). If you resolve links scraped from web pages, handle a reference that starts with?or is empty yourself.- The last line is the classic bug with API base URLs: a base without a trailing slash loses its last segment. Store base URLs with a trailing
/and resolve paths without a leading/. normalize()removes.and..segments. It doesn't lowercase the scheme or host, remove default ports or decode unreserved characters.relativize()is the reverse ofresolve(), but it only works when the target is under the base's path. Otherwise it returns the target unchanged.
URI, URL, Path and host names
import java.net.IDN;
import java.net.MalformedURLException;
import java.net.URI;
import java.net.URL;
import java.nio.file.Path;
public class Interop {
public static void main(String[] args) throws Exception {
// URI -> URL: needs an absolute URI with a scheme the JDK has a handler for
URL url = URI.create("https://example.com/a%20b?x=1").toURL();
System.out.println("URL: " + url + ", file=" + url.getFile() + ", defaultPort=" + url.getDefaultPort());
try {
URI.create("redis://localhost:6379/0").toURL();
} catch (MalformedURLException e) {
System.out.println("toURL: " + e.getMessage());
}
try {
URI.create("/relative/path").toURL();
} catch (IllegalArgumentException e) {
System.out.println("toURL: " + e.getMessage());
}
// Equality: URI compares text (scheme and host case-insensitively)
System.out.println(URI.create("HTTPS://Example.COM/a").equals(URI.create("https://example.com/a")));
System.out.println(URI.create("https://example.com/a%7e").equals(URI.create("https://example.com/a%7E")));
System.out.println(URI.create("https://example.com:443/a").equals(URI.create("https://example.com/a")));
// file: URIs and paths
Path p = Path.of("C:/Users/alice/My Documents/notes.txt");
URI fileUri = p.toUri();
System.out.println(fileUri);
System.out.println(Path.of(fileUri));
// Internationalized domain names
URI idn = URI.create("https://münchen.example/stadtplan");
System.out.println("host=" + idn.getHost() + ", authority=" + idn.getAuthority());
String ascii = IDN.toASCII("münchen.example");
System.out.println(ascii + " <- " + IDN.toUnicode(ascii));
System.out.println(URI.create("https://" + ascii + "/stadtplan").getHost());
}
}
Output:
URL: https://example.com/a%20b?x=1, file=/a%20b?x=1, defaultPort=443
toURL: unknown protocol: redis
toURL: URI is not absolute
true
true
false
file:///C:/Users/alice/My%20Documents/notes.txt
C:\Users\alice\My Documents\notes.txt
host=null, authority=münchen.example
xn--mnchen-3ya.example <- münchen.example
xn--mnchen-3ya.example
toURL()fails for relative URIs and for schemes without a JDK protocol handler (redis,postgresql). The URI itself was fine, so parse connection strings likeredis://localhost:6379/0as aURIand never convert them.URI.equals()compares scheme and host case-insensitively, percent escapes case-insensitively and everything else exactly.https://example.com:443/aandhttps://example.com/aare different URIs although they point to the same resource. For "same resource" checks, normalize both sides first: lowercase scheme and host, drop default ports,normalize()the path.Path.toUri()andPath.of(URI)convert between file paths andfile:URIs, handling spaces and drive letters. Don't buildfile:URIs by string concatenation.- An internationalized domain name such as
münchen.exampleparses, butgetHost()returnsnull, because the parser only accepts ASCII host names. Convert it withIDN.toASCII()to its Punycode form (xn--...) first. That's also the form DNS and TLS certificates use.
Validating URLs from users
URLs that come from users end up in redirects (?next=/account), webhooks and server-side fetches. The checks that matter are on the parsed result, not on the string: startsWith("https://example.com") and contains("example.com") are easy to fool. Here's an allowlist check for a redirect target:
import java.net.URI;
import java.net.URISyntaxException;
import java.util.Locale;
import java.util.Set;
public class Validate {
static final Set<String> ALLOWED_HOSTS = Set.of("example.com", "www.example.com");
// Returns a cleaned-up URI, or throws with a reason
static URI checkRedirect(String input) throws URISyntaxException {
URI uri = new URI(input.strip()).parseServerAuthority().normalize();
String scheme = uri.getScheme();
if (scheme == null || !(scheme.equalsIgnoreCase("https") || scheme.equalsIgnoreCase("http"))) {
throw new URISyntaxException(input, "scheme must be http or https");
}
if (uri.getRawUserInfo() != null) {
throw new URISyntaxException(input, "user info not allowed");
}
String host = uri.getHost() == null ? null : uri.getHost().toLowerCase(Locale.ROOT);
if (host == null || !ALLOWED_HOSTS.contains(host)) {
throw new URISyntaxException(input, "host not allowed: " + host);
}
if (uri.getPort() != -1 && uri.getPort() != 443 && uri.getPort() != 80) {
throw new URISyntaxException(input, "port not allowed");
}
return uri;
}
public static void main(String[] args) {
String[] inputs = {
"https://www.example.com/account/../orders?id=7",
" https://EXAMPLE.com/ ",
"https://example.com@evil.test/",
"https://evil.test/?next=example.com",
"https://example.com.evil.test/",
"javascript:alert(1)",
"//evil.test/path",
"https://example.com:6379/",
"https://exam ple.com/",
};
for (String in : inputs) {
try {
System.out.println("OK " + checkRedirect(in));
} catch (URISyntaxException e) {
System.out.println("REJECT " + in.strip() + " (" + e.getReason() + ")");
}
}
}
}
Output:
OK https://www.example.com/orders?id=7
OK https://EXAMPLE.com/
REJECT https://example.com@evil.test/ (user info not allowed)
REJECT https://evil.test/?next=example.com (host not allowed: evil.test)
REJECT https://example.com.evil.test/ (host not allowed: example.com.evil.test)
REJECT javascript:alert(1) (scheme must be http or https)
REJECT //evil.test/path (scheme must be http or https)
REJECT https://example.com:6379/ (port not allowed)
REJECT https://exam ple.com/ (Illegal character in authority)
https://example.com@evil.test/is the classic trick:example.comis the user info and the host isevil.test. Parsing exposes it, string matching doesn't.https://example.com.evil.test/passes astartsWith()orcontains()check but not an exact host comparison. For "any subdomain" usehost.equals(d) || host.endsWith("." + d).javascript:and scheme-relative//evil.testURLs are rejected by requiring the scheme.parseServerAuthority()makes suregetHost()is a real host name, andnormalize()removes..segments before you look at the path.- For a redirect that must stay on your own site, it's simpler to accept only a path: check that it starts with a single
/(not//or/\) and has no scheme or authority. - For server-side fetches (webhooks, link previews) an allowlist of hosts isn't enough when users can name any host. Resolve the host and refuse private, loopback and link-local addresses (
InetAddress.isSiteLocalAddress(),isLoopbackAddress(),isLinkLocalAddress()), and turn off automatic redirects so a public URL can't redirect to an internal one.
Summary
- Use
java.net.URIto parse URLs. UseURI.create()for trusted literals andnew URI(String)withURISyntaxExceptionfor input. AvoidURLconstructors andURL.equals(). - Getters return decoded parts. The
getRaw*()getters return the encoded text. Split the raw query and raw path before decoding. - Missing parts are
null, a missing port is-1. Host names with underscores or non-ASCII characters give anullhost;parseServerAuthority()makes that an error. - Parse query strings with a small function: split
getRawQuery()on&and=, decode withURLDecoder.decode(s, UTF_8), collect repeated keys into lists. - Build URLs by encoding each value with
URLEncoder.encode(s, UTF_8)(and+to%20in paths), then joining. resolve()turns relative links into absolute ones. Keep a trailing/on base URLs.- Validate user-supplied URLs on the parsed scheme, user info, host and port, not with string matching.