URL-Encoding

Juneau supports converting arbitrary POJOs to and from URL-encoded strings using ultra-efficient serializers and parsers.

The serializer converts POJOs directly to URL-encoded strings without the need for intermediate DOM objects using a highly-efficient state machine. Likewise, the parser creates POJOs directly from URL-encoded strings without the need for intermediate DOM objects.

Juneau uses UON (URL-Encoded Object Notation) for representing POJOs as URL-Encoded values in key-value pairs.

The UON specification can be found here.

The following example shows JSON for a typical bean:

Sample Beans

public class Person {

    // Bean properties
    public String name;
    @MarshalledProp(calendarFormat=CalendarFormat.ISO_INSTANT) public Calendar birthDate;
    public List addresses;

    // Getters/setters omitted
}

public class Address {

    // Bean properties
    public String street, city;
    public StateEnum state;
    public int zip;
    public boolean isCurrent;

    // Getters/setters omitted
}

Sample Code

Person person = new Person()
    .name("John Smith")
    .birthDate("1946-08-12T00:00:00Z")
    .addresses(
        new Address()
            .street("100 Main Street")
            .city("Anywhereville")
            .state(NY)
            .zip(12345)
            .isCurrent(true)
    );

URL-Encoding

name='John+Smith'
&birthDate='1946-08-12T00:00:00Z'
&addresses=@(
    (
        street='100 Main Street',
        city=Anywhereville,
        state=NY,
        zip=12345,
        isCurrent=true
    )
)

URL-Encoding methodology

Java type	JSON equivalent	UON
Maps/beans	OBJECT	a1=(b1=x1,b2=x2) a1=(b1=(c1=x1,c2=x2))
Collections/arrays	ARRAY	a1=@(x1,x2) a1=@(@(x1,x2),@(x3,x4)) a1=@((b1=x1,b2=x2),(c1=x1,c2=x2))
Booleans	BOOLEAN	a1=true&a2=false
int/float/double/...	NUMBER	a1=123&a2=1.23e1
null	NULL	a1=null
String	STRING	a1=foobar a1='true' a1='null' a1='123' a1=' string with whitespace ' a1='string with ~'escaped~' quotes'

Refer to the UON specification for a complete set of syntax rules.

In This Section

📄️ 2.2.29.1. URL-Encoding Serializers

The UrlEncodingSerializer class is used to

📄️ 2.2.29.2. URL-Encoding Parsers

The UrlEncodingParser class is used to parse

📄️ 2.2.29.3. @UrlEncoding Annotation

The URL-Encoding format provides two annotations for tailoring how beans are serialized and parsed: