README.md

URL Encoder for Java

A simple defensive library to encode/decode URL components.

This library was extracted from the RIFE2 Web Application Framework.
A Kotlin Multiplatform version can also be found at https://github.com/ethauvin/urlencoder.

The rules are determined by combining the unreserved character set from RFC 3986 with the percent-encode set from application/x-www-form-urlencoded.

Both specs above support percent decoding of two hexadecimal digits to a binary octet, however their unreserved set of characters differs and application/x-www-form-urlencoded adds conversion of space to +, that has the potential to be misunderstood.

This class encodes with rules that will be decoded correctly in either case.

Additionally, this library allocates no memory when encoding isn't needed and does the work in a single pass without multiple loops. Both of these optimizations have a significantly beneficial impact on performance of encoding compared to other solutions like the standard URLEncoder in the JDK or UriUtils in Spring.

Examples (TL;DR)

UrlEncoder.encode("a test &");           // -> "a%20test%20%26"
UrlEncoder.encode("%#okékÉȢ smile!😁");  // -> "%25%23ok%C3%A9k%C3%89%C8%A2%20smile%21%F0%9F%98%81"
UrlEncoder.encode("?test=a test", "?="); // -> "?test=a%20test"
UrlEncoder.encode("foo bar", true);      // -> "foo+bar" (encode space to +)        

UrlEncoder.decode("a%20test%20%26");     // -> "a test &"
UrlEncoder.decode("%25%23ok%C3%A9k%C3%89%C8%A2%20smile%21%F0%9F%98%81"); // -> "%#okékÉȢ smile!😁"
UrlEncoder.decode("foo+bar", true);      // -> "foo bar" (decode + to space)

Gradle, Maven, etc.

To use with Gradle, include the following dependency in your build file:

dependencies {
    implementation("com.uwyn:urlencoder:1.2.0")
}

Instructions for using with Maven, Ivy, etc. can be found on Maven Central.

Standalone usage

UrlEncoder can be used on the command line also, both for encoding and decoding.

You have two options:

• run it with Gradle
• build the jar and launch it with Java

The usage is as follows:

Encode and decode URL components defensively.
  -e  encode (default)
  -d  decode

Running with Gradle

./gradlew run --args="-e 'a test &'"        # -> a%20test%20%26
./gradlew run --args="%#okékÉȢ"             # -> %25%23ok%C3%A9k%C3%89%C8%A2

./gradlew run --args="-d 'a%20test%20%26'"  # -> a test &

Running with Java

First build the jar file:

./gradlew clean jar

Then run it:

java -jar lib/build/libs/urlencoder-*.jar -e "a test &"       # -> a%20test%20%26
java -jar lib/build/libs/urlencoder-*.jar "%#okékÉȢ"          # -> %25%23ok%C3%A9k%C3%89%C8%A2

java -jar lib/build/libs/urlencoder-*.jar -d "a%20test%20%26" # -> a test &

Why not simply use java.net.URLEncoder?

Apart for being quite inefficient, some URL components encoded with URLEncoder.encode might not be able to be properly decoded.

For example, a simply search query such as:

var u = URLEncoder.encode("foo +bar", StandardCharsets.UTF_8);

would be encoded as:

foo+%2Bbar

Trying to decode it with Spring, for example:

UriUtils.decode(u, StandardCharsets.UTF_8));

would return:

foo++bar

Unfortunately, decoding with Uri.decode on Android, decodeURI in Javascript, etc. would yield the exact same result.