URL and URI

url encoding/decoding

URLEncoder/URLDecoder classes are used to encode or decode strings that are used in query string for GET requests or POST requests with the "application/x-www-form-urlencoded" MIME format. When encoding a String, the following rules apply:

• the alphanumeric characters "a" through "z", "A" through "Z" and "0" through "9" remain the same
• the special characters ".", "-", "*", and "_" remain the same
• the space character is converted into a plus sign
• all other characters are represented as %xy, where xy is the two-digit hexadecimal representation of the byte. The recommended encoding scheme to use is UTF-8.

And finally, make sure to encode whitespace using "+" or "%20" in the query string, and using "%20" within the rest of the URL.

// prepare query string
StringJoiner sj = new StringJoiner("&");
for (Map.Entry<String, String> entry : params.entrySet()) {
    sj.add(URLEncoder.encode(entry.getKey(), "UTF-8") + "="
        + URLEncoder.encode(entry.getValue(), "UTF-8"));
}
    
// make something like http://example.com?param1=blabla&param2=34
String url = urlBase + "?" + sj.toString; 
// "http://example.com/with spaces/ã.jpg?param=Ы Ю"
URI uri = URI(
     "http",
     "example.com",
     "/with spaces/ã.jpg",
     "param=Ы Ю",
     null);

//: http://example.com/with%20spaces/%C3%A3.jpg?param=%D0%AB%20%D0%AE
System.out.println(uri.toASCIIString());
 
//: http://example.com/with%20spaces/ã.jpg?param=Ы%20Ю
System.out.println(uri.toUrl()); // or uri.toString
        
//: http%3A%2F%2Fexample.com%2Fwith+spaces%2F%C3%A3.jpg%3Fparam%3D%D0%AB+%D0%AE
System.out.println( URLEncoder.encode(
        "http://example.com/with spaces/ã.jpg?param=Ы Ю",
        "UTF-8");

URL

The URL class represents a URL. The main functionality is access to the resource and getting various parts of the url.

URI

The URI class represents a URI.

When you create URI from components, components will be encoded automatically.

When you create a URI by parsing a string, an exception may be thrown if the uri string contains an invalid character.

// url contains invalid characters
String strUrl = "http://example.com/with spaces/ã.jpg?param=Ы Ю";
URL url = URL(strUrl);  

URI uri1 = URI(strUrl); // exception
URI uri2 = URI.create(strUrl); // exception
URI uri3 = url.toURI(); // exception

// ok
URI uri = URI("http", "example.com", "/with spaces/ã.jpg", "param=Ы Ю", null);
URI uri4 = URI(url.getProtocol(), url.getUserInfo(), url.getHost(), 
               url.getPort(), url.getPath(), url.getQuery(), 
               url.getRef()); 

The main functionality of the URI is getting various parts of the uri like the URL class and transformation of uri (see below in table).