Parsing URLs

suggest change

A 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:

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:

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/

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&note=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&note=a&b=c&debug&&empty=

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

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.

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

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

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)

Summary

Feedback about page:

Feedback:
Optional: your email if you want me to get back to you:



Table Of Contents