{title:'URIs', updated:'9.0.0'}

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:

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

Juneau automatically interprets any {@link java.net.URL} and {@link java.net.URI} objects as URIs and will resolve them accordingly. The {@link oaj.annotation.Uri @Uri} annotation can be used to extend that to other bean properties and class types so that they also get interpreted as URIs. For 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() { | ... | } | }