It is a common practice to URL encode the query strings or form parameters while calling a remote web service to avoid cross-site attacks. URL encoding converts a string into a valid URL format that makes the transmitted data more reliable and secure.

In this article, you will learn how to URL encode or decode query strings and form parameters using Java.

URL Encoding in Java

You can easily encode a URL string or a form parameter into a valid URL format by using the URLEncoder class in Java. This utility class contains static methods for converting a string into the application/x-www-form-urlencoded MIME format.

The following example shows how to use the URLEncoder.encode() method to perform URL encoding in Java:

try {
    // base url
    String baseURL = "https://www.google.com/search?q=";

    // query string
    String query = "Dankeschön für Ihre €100";

    // URL encode query string
    String encodeStr = URLEncoder.encode(query, StandardCharsets.UTF_8.name());

    // final url
    String url = baseURL + encodeStr;

    // print the url
    System.out.println(url);

} catch (UnsupportedEncodingException ex) {
    ex.printStackTrace();
}

Here is how the encoded URL looks like:

https://www.google.com/search?q=Dankesch%C3%B6n+f%C3%BCr+Ihre+%E2%82%AC100

The encode() method takes two parameters:

  1. str — The string to be encoded.
  2. encodingScheme — The name of the character encoding. In the above example, we used the UTF-8 encoding scheme. The World Wide Web Consortium recommends that UTF-8 encoding scheme should be used whenever possible to avoid incompatibilities. If the given encoding is not supported, an UnsupportedEncodingException is thrown.

Common Pitfall: When performing URL encoding, don't encode the entire URL. Only encode the individual query string parameter value or portion of the URI (path segment).

Let us have another example with multiple query string parameters encoding:

// request parameters
Map<String, String> params = new HashMap<>();
params.put("name", "John @ Doe");
params.put("email", "john.doe@example.com");
params.put("password", "$34!%&#78!(d");
params.put("phone", "+1 (4566) 788-565");

// create a URL encoded string
String encodedURL = params.entrySet().stream()
        .map(entry -> {
            try {
                return entry.getKey() + "=" + URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8.name());
            } catch (UnsupportedEncodingException e) {
                e.printStackTrace();
            }
            return "";
        })
        .collect(Collectors.joining("&", "http://example.com?", ""));

// print the url
System.out.println(encodedURL);

Here is how the output looks like:

http://example.com?password=%2434%21%25%26%2378%21%28d&phone=%2B1+%284566%29+788-565&name=John+%40+Doe&email=john.doe%40example.com

How URL Encoding Works

When URL encoding a string, the following rules apply:

  • The alphanumeric characters (a-z, A-Z, and 0-9) remain the same.
  • The special characters ., -, *, and _ remain the same.
  • The white space character " " is converted into a + sign. This is opposite to other programming languages like JavaScript which encodes the space character into %20. But it is completely valid as the spaces in query string parameters are represented by +, and not %20. The %20 is generally used to represent spaces in URI itself (the URL part before ?).
  • All other characters are considered unsafe and are first converted into one or more bytes using the given encoding scheme. Then each byte is represented by the 3-character string %XY, where XY is the two-digit hexadecimal representation of the byte.

URL Decoding in Java

URL decoding is the process of converting URL encoding query strings and form parameters into their original form. By default, HTML form parameters are encoded using application/x-www-form-urlencoded MIME type. Before using them in your application, you must decode them. Same is the case with query string parameters included in the URL.

Most of the times, these parameters are already decoded by the framework you're using in your application like Spring or Express. But in a standalone Java application, you must manually decode query string and form parameters by using the URLDecoder utility class.

The following example uses the URLDecoder.decode() method to perform URL decoding in Java:

try {
    // encoded URL
    String encodedURL = "https://www.google.com/search?q=Dankesch%C3%B6n+f%C3%BCr+Ihre+%E2%82%AC100";

    // decode URL
    String url = URLDecoder.decode(encodedURL, StandardCharsets.UTF_8.name());

    // print the url
    System.out.println(url);
} catch (UnsupportedEncodingException ex) {
    ex.printStackTrace();
}

Here is the original URL printed on the console:

https://www.google.com/search?q=Dankeschön für Ihre €100

The decode() method accepts two parameters:

  1. str — The string to be decoded.
  2. encodingScheme — The name of the character encoding scheme. It is recommended to use the UTF-8 encoding to avoid incompatibilities with other systems.

The decoding process is the opposite of that used by the URLEncoder class. It is assumed that all characters in the encoded string are one of the following: a through z, A through Z, 0 through 9, and -, _, ., and *. The character % is permitted but is interpreted as the start of a special escaped sequence.

Read Next: Base64 Encoding and Decoding in Java

✌️ Like this article? Follow @attacomsian on Twitter. You can also follow me on LinkedIn and DEV. Buy me a coffee (cost $3)

Need help to start a new Spring Boot or MEAN stack project? I am available for contract work. Hire me to accomplish your business goals with engineering and design. Let’s talk about your project: hi@attacomsian.com.