juneau-doc/docs/Topics/02.juneau-marshall/18.URIs.html

<!--
/***************************************************************************************************************************
 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *  
 *  http://www.apache.org/licenses/LICENSE-2.0
 *  
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations under the License.
 ***************************************************************************************************************************/
 -->

URIs

<p>
	Juneau serializers have sophisticated support for transforming relative URIs to absolute form.
</p>
<p>
	The classes and settings that control the behavior are:
</p>
<ul class='javatree'>
	<li class='jc'>{@link oaj.UriResolver} 
	<li class='jc'>{@link oaj.UriContext}
	<li class='jc'>{@link oaj.UriRelativity}
	<li class='jc'>{@link oaj.UriResolution}
	<li class='jac'>{@link oaj.serializer.Serializer}
	<ul>
		<li class='jf'>{@link oaj.serializer.Serializer#SERIALIZER_uriContext}
		<li class='jf'>{@link oaj.serializer.Serializer#SERIALIZER_uriRelativity}
		<li class='jf'>{@link oaj.serializer.Serializer#SERIALIZER_uriResolution}
	</ul> 
</ul>
<p>
	The following example shows a bean containing URIs of various forms and how they end up serialized. 
</p>
<p class='bpcode w800'>
	<jc>// Our bean with properties containing various kinds of URIs.</jc>
	<jk>public class</jk> TestURIs {
		<jk>public</jk> URI
			<jf>f1a</jf> = URI.<jsm>create</jsm>(<js>"http://www.apache.org/f1a"</js>),
			<jf>f1b</jf> = URI.<jsm>create</jsm>(<js>"/f1b"</js>),
			<jf>f1c</jf> = URI.<jsm>create</jsm>(<js>"/f1c/x/y"</js>),
			<jf>f1d</jf> = URI.<jsm>create</jsm>(<js>"f1d"</js>),
			<jf>f1e</jf> = URI.<jsm>create</jsm>(<js>"f1e/x/y"</js>),
			<jf>f1f</jf> = URI.<jsm>create</jsm>(<js>""</js>),
			<jf>f2a</jf> = URI.<jsm>create</jsm>(<js>"context:/f2a/x"</js>),
			<jf>f2b</jf> = URI.<jsm>create</jsm>(<js>"context:/f2b"</js>),
			<jf>f2c</jf> = URI.<jsm>create</jsm>(<js>"context:/"</js>),
			<jf>f2d</jf> = URI.<jsm>create</jsm>(<js>"context:/.."</js>),
			<jf>f3a</jf> = URI.<jsm>create</jsm>(<js>"servlet:/f3a/x"</js>),
			<jf>f3b</jf> = URI.<jsm>create</jsm>(<js>"servlet:/f3b"</js>),
			<jf>f3c</jf> = URI.<jsm>create</jsm>(<js>"servlet:/"</js>),
			<jf>f3d</jf> = URI.<jsm>create</jsm>(<js>"servlet:/.."</js>),
			<jf>f4a</jf> = URI.<jsm>create</jsm>(<js>"request:/f4a/x"</js>),
			<jf>f4b</jf> = URI.<jsm>create</jsm>(<js>"request:/f4b"</js>),
			<jf>f4c</jf> = URI.<jsm>create</jsm>(<js>"request:/"</js>),
			<jf>f4d</jf> = URI.<jsm>create</jsm>(<js>"request:/.."</js>);;
	}	
	
	<jc>// Create a serializer.</jc>
	WriterSerializer s = JsonSerializer
		<jsm>create</jsm>()
		.simple()
		.uriContext(<js>"{authority:'http://foo.com:123',contextRoot:'/myContext',servletPath:'/myServlet',pathInfo:'/myPath'}"</js>)
		.uriResolution(<jsf>ABSOLUTE</jsf>)
		.uriRelativity(<jsf>RESOURCE</jsf>)
		.build();
		
	<jc>// Produces:</jc>
	<jc>// {</jc>
	<jc>//	f1a:'http://www.apache.org/f1a',</jc>
	<jc>//	f1b:'http://foo.com:123/f1b',</jc>
	<jc>//	f1c:'http://foo.com:123/f1c/x/y',</jc>
	<jc>//	f1d:'http://foo.com:123/myContext/myServlet/f1d',</jc>
	<jc>//	f1e:'http://foo.com:123/myContext/myServlet/f1e/x/y',</jc>
	<jc>//	f1f:'http://foo.com:123/myContext/myServlet',</jc>
	<jc>//	f2a:'http://foo.com:123/myContext/f2a/x',</jc>
	<jc>//	f2b:'http://foo.com:123/myContext/f2b',</jc>
	<jc>//	f2c:'http://foo.com:123/myContext',</jc>
	<jc>//	f2d:'http://foo.com:123'</jc>
	<jc>//	f3a:'http://foo.com:123/myContext/myServlet/f3a/x',</jc>
	<jc>//	f3b:'http://foo.com:123/myContext/myServlet/f3b',</jc>
	<jc>//	f3c:'http://foo.com:123/myContext/myServlet',</jc>
	<jc>//	f3d:'http://foo.com:123/myContext',</jc>
	<jc>//	f4a:'http://foo.com:123/myContext/myServlet/myPath/f4a/x',</jc>
	<jc>//	f4b:'http://foo.com:123/myContext/myServlet/myPath/f4b',</jc>
	<jc>//	f4c:'http://foo.com:123/myContext/myServlet/myPath',</jc>
	<jc>//	f4d:'http://foo.com:123/myContext/myServlet'</jc>
	<jc>// }</jc>
	String json = s.serialize(<jk>new</jk> TestURIs());
</p>
<p>
	URI resolution is controlled by the following settings:
</p>
<ul class='javatree'>
	<li class='jf'>{@link oaj.serializer.Serializer#SERIALIZER_uriContext}
		<br>Setting that defines the URI contextual information used to resolve relative URIs.
	<li class='jf'>{@link oaj.serializer.Serializer#SERIALIZER_uriRelativity}
		<br>Setting that defines how relative URIs should be interpreted.
		<br>Possible values:
		<ul>
			<li class='jf'>{@link oaj.UriRelativity#RESOURCE}
				<br>Relative URIs should be considered relative to the servlet URI.
				<br>(e.g. <js>"http://host:port/context-root/servlet-path"</js>).
			<li class='jf'>{@link oaj.UriRelativity#PATH_INFO}
				<br>Relative URIs should be considered relative to the request URI.
				<br>(e.g. <js>"http://host:port/context-root/servlet-path/path-info"</js>).
		</ul>
	<li class='jf'>{@link oaj.serializer.Serializer#SERIALIZER_uriResolution}
		<br>Setting that defines the final format of serialized URIs.
		<br>Possible values:
		<ul>
			<li class='jf'>{@link oaj.UriResolution#ABSOLUTE}
				<br>Resolve to an absolute URL.
				<br>(e.g. <js>"http://host:port/context-root/servlet-path/path-info"</js>).
			<li class='jf'>{@link oaj.UriResolution#ROOT_RELATIVE}
				<br>Resolve to a root-relative URL.
				<br>(e.g. <js>"/context-root/servlet-path/path-info"</js>).
			<li class='jf'>{@link oaj.UriResolution#NONE}
				<br>Don't do any URL resolution.
		</ul>
</ul>
<p>
	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:
</p>
<p class='bpcode w800'>
	<jc>// Applied to a class whose toString() method returns a URI.</jc>
	<ja>@URI</ja>
	<jk>public class</jk> MyURI {
		<ja>@Override</ja> <jc>/* Object */</jc>
		<jk>public</jk> String toString() {
			<jk>return</jk> <js>"http://localhost:9080/foo/bar"</js>;
		}
	}

	<jc>// Applied to bean properties</jc>
	<jk>public class</jk> MyBean {

		<ja>@URI</ja>
		<jk>public</jk> String <jf>beanUri</jf>;

		<ja>@URI</ja>
		<jk>public</jk> String getParentUri() {
			...
		}
	}
</p>