URIs

Juneau serializers have sophisticated support for transforming relative URIs to absolute form.

The following example shows a bean containing URIs of various forms and how they end up serialized.

// Our bean with properties containing various kinds of URIs.
public class TestURIs {
    public URI
        a = URI.create("http://www.apache.org/a"),
        b = URI.create("/b"),
        c = URI.create("/c/x/y"),
        d = URI.create("d"),
        e = URI.create("e/x/y"),
        f = URI.create(""),
        g = URI.create("context:/g/x"),
        h = URI.create("context:/h"),
        i = URI.create("context:/"),
        j = URI.create("context:/.."),
        k = URI.create("servlet:/k/x"),
        l = URI.create("servlet:/l"),
        m = URI.create("servlet:/"),
        n = URI.create("servlet:/.."),
        o = URI.create("request:/o/x"),
        p = URI.create("request:/p"),
        q = URI.create("request:/"),
        r = URI.create("request:/..");
}

// Create a serializer.
WriterSerializer serializer = JsonSerializer
    create()
    .simple()
    .uriContext(
        UriContext.of(
            "http://foo.com:123",  // Authority
            "/myContext",  // Context root
            "/myServlet",  // Servlet path
            "/myPath"  // Path info
        )
    )
    .uriResolution(ABSOLUTE)
    .uriRelativity(RESOURCE)
    .build();

// Produces:
// {
//	a:'http://www.apache.org/a',
//	b:'http://foo.com:123/b',
//	c:'http://foo.com:123/c/x/y',
//	d:'http://foo.com:123/myContext/myServlet/d',
//	e:'http://foo.com:123/myContext/myServlet/e/x/y',
//	f:'http://foo.com:123/myContext/myServlet',
//	g:'http://foo.com:123/myContext/g/x',
//	h:'http://foo.com:123/myContext/h',
//	i:'http://foo.com:123/myContext',
//	j:'http://foo.com:123'
//	k:'http://foo.com:123/myContext/myServlet/k/x',
//	l:'http://foo.com:123/myContext/myServlet/l',
//	m:'http://foo.com:123/myContext/myServlet',
//	n:'http://foo.com:123/myContext',
//	o:'http://foo.com:123/myContext/myServlet/myPath/o/x',
//	p:'http://foo.com:123/myContext/myServlet/myPath/p',
//	q:'http://foo.com:123/myContext/myServlet/myPath',
//	r:'http://foo.com:123/myContext/myServlet'
// }
String json = serializer.serialize(new TestURIs());

URI resolution is controlled by the following settings:

Serializer.BuilderuriContext(UriContext) - Setting that defines the URI contextual information used to resolve relative URIs.uriRelativity(UriRelativity) - Setting that defines how relative URIs should be interpreted. Possible values:UriRelativity.RESOURCE - Relative URIs should be considered relative to the servlet URI. (e.g. http://host:port/context-root/servlet-path).UriRelativity.PATH_INFO - Relative URIs should be considered relative to the request URI. (e.g. http://host:port/context-root/servlet-path/path-info).uriResolution(UriResolution) - Setting that defines the final format of serialized URIs. Possible values:UriResolution.ABSOLUTE - Resolve to an absolute URL. (e.g. http://host:port/context-root/servlet-path/path-info).UriResolution.ROOT_RELATIVE - Resolve to a root-relative URL. (e.g. "/context-root/servlet-path/path-info").UriResolution.NONE - Don't do any URL resolution.

Juneau automatically interprets any URL and URI objects as URIs and will resolve them accordingly. The @Uri annotation can be used to extend that to other bean properties and class types so that they also get interpreted as URIs.

Example

// Applied to a class whose toString() method returns a URI.
@URI
public class MyURI {
    @Override /* Object */
    public String toString() {
        return "http://localhost:9080/foo/bar";
    }
}

// Applied to bean properties
public class MyBean {

    @URI
    public String beanUri;

    @URI
    public String getParentUri() {
        ...
    }
}