{updated} URIs

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

The classes and settings that control the behavior are:

- {@link oaj.UriResolver}
- {@link oaj.UriContext}
- {@link oaj.UriRelativity}
- {@link oaj.UriResolution}
- {@link oaj.serializer.Serializer}
  - {@link oaj.serializer.Serializer#SERIALIZER_uriContext}
  - {@link oaj.serializer.Serializer#SERIALIZER_uriRelativity}
  - {@link oaj.serializer.Serializer#SERIALIZER_uriResolution}

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 f1a = URI.create("http://www.apache.org/f1a"), f1b = URI.create("/f1b"), f1c = URI.create("/f1c/x/y"), f1d = URI.create("f1d"), f1e = URI.create("f1e/x/y"), f1f = URI.create(""), f2a = URI.create("context:/f2a/x"), f2b = URI.create("context:/f2b"), f2c = URI.create("context:/"), f2d = URI.create("context:/.."), f3a = URI.create("servlet:/f3a/x"), f3b = URI.create("servlet:/f3b"), f3c = URI.create("servlet:/"), f3d = URI.create("servlet:/.."), f4a = URI.create("request:/f4a/x"), f4b = URI.create("request:/f4b"), f4c = URI.create("request:/"), f4d = URI.create("request:/..");; } // Create a serializer. WriterSerializer s = JsonSerializer create() .simple() .uriContext("{authority:'http://foo.com:123',contextRoot:'/myContext',servletPath:'/myServlet',pathInfo:'/myPath'}") .uriResolution(ABSOLUTE) .uriRelativity(RESOURCE) .build(); // Produces: // { // f1a:'http://www.apache.org/f1a', // f1b:'http://foo.com:123/f1b', // f1c:'http://foo.com:123/f1c/x/y', // f1d:'http://foo.com:123/myContext/myServlet/f1d', // f1e:'http://foo.com:123/myContext/myServlet/f1e/x/y', // f1f:'http://foo.com:123/myContext/myServlet', // f2a:'http://foo.com:123/myContext/f2a/x', // f2b:'http://foo.com:123/myContext/f2b', // f2c:'http://foo.com:123/myContext', // f2d:'http://foo.com:123' // f3a:'http://foo.com:123/myContext/myServlet/f3a/x', // f3b:'http://foo.com:123/myContext/myServlet/f3b', // f3c:'http://foo.com:123/myContext/myServlet', // f3d:'http://foo.com:123/myContext', // f4a:'http://foo.com:123/myContext/myServlet/myPath/f4a/x', // f4b:'http://foo.com:123/myContext/myServlet/myPath/f4b', // f4c:'http://foo.com:123/myContext/myServlet/myPath', // f4d:'http://foo.com:123/myContext/myServlet' // } String json = s.serialize(new TestURIs());

URI resolution is controlled by the following settings:

- {@link oaj.serializer.Serializer#SERIALIZER_uriContext}
  Setting that defines the URI contextual information used to resolve relative URIs.
- {@link oaj.serializer.Serializer#SERIALIZER_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#SERIALIZER_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() { ... } }