UON

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

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

Juneau uses UON (URL-Encoded Object Notation) for representing POJOs.

The UON specification can be found here.

The following examples use 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)
    );

UON

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

Annotations

@UonConfig sets serializer/parser properties on a REST class or method (see Context Annotations). Attributes are strings:

Attribute	Description
addBeanTypes	Add _type properties to beans whose type can't be inferred through reflection (default false).
encoding	Encode non-valid URI characters as %xx (serializer).
decoding	Decode %xx sequences (parser); set false if the input was already decoded.
paramFormat	Format for query/form-data/header values: UON (default) or PLAINTEXT.
validateEnd	After parsing, verify the remaining input is only whitespace/comments (default false).
rank	Ordering relative to other config annotations.

@Rest
@UonConfig(paramFormat="PLAINTEXT", validateEnd="true")
public class MyResource extends BasicRestServlet { ... }

@Uon is a class/method/field marker (its only attribute is description), and @UonApply applies it to other classes/members via on()/onClass() (see Dynamically Applied Annotations).

UON 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.28.1. UON Serializers

The UonSerializer class is used to serialize POJOs into UON.

📄️ 2.2.28.2. UON Parsers

The UonParser class is used to parse UON into POJOs.