<!--
/***************************************************************************************************************************
 * 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.
 ***************************************************************************************************************************/
 -->

@Rest(path)

<p>
	The {@link oajr.annotation.RestResource#path() @RestResource(path)} annotation is used in the following situations:
<p>
<ul class='spaced-list'>
	<li>
		On child resources (resource classes attached to parents via the {@link oajr.annotation.RestResource#children() @RestResource(children)} annotation) to identify
		the subpath used to access the child resource relative to the parent.
	<li>
		On top-level {@link oajr.RestServlet} classes deployed as Spring beans when {@link oajr.springboot.JuneauRestInitializer} is being used.
</ul>

<h5 class='topic'>On child resources</h5>
<p>
	The typical usage is to define a path to a child resource relative to the parent resource.
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@RestResource</ja>(
		children={
			ChildResource.<jk>class</jk>
		}
	)
	<jk>public class</jk> TopLevelResource <jk>extends</jk> BasicRestServlet {...}
</p>
<p class='bpcode w800'>
	<ja>@RestResource</ja>(
		path=<js>"/child"</js>,
		children={
			GrandchildResource.<jk>class</jk>
		}
	)
	<jk>public class</jk> ChildResource {...}
</p>
<p class='bpcode w800'>
	<ja>@RestResource</ja>(
		path=<js>"/grandchild"</js>
	)
	<jk>public class</jk> GrandchildResource {
		<ja>@RestMethod</ja>(
			path=<js>"/"</js>
		)
		<jk>public</jk> String sayHello() {
			<jk>return</jk> <js>"Hello!"</js>;
		}
	}
</p>
<p>
	In the example above, assuming the <c>TopLevelResource</c> servlet is deployed to path <c>/myContext/myServlet</c>,
	then the <c>sayHello</c> method is accessible through the URI <c>/myContext/myServlet/child/grandchild</c>.
</p>
<p>
	Note that in this scenario, the <c>path</c> attribute is not defined on the top-level resource.
	Specifying the path on the top-level resource has no effect, but can be used for readability purposes.
</p>

<h5 class='topic'>On top-level resources deployed as Spring beans</h5>
<p>
	The path can also be used on top-level resources deployed as Spring beans when used with the {@link oajr.springboot.JuneauRestInitializer}
	Spring Boot initializer class:
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode w800'>
	<ja>@SpringBootApplication</ja>
	<ja>@Controller</ja>
	<jk>public class</jk> App {

		<jc>// Our entry-point method.</jc>
		<jk>public static void</jk> main(String[] args) {
			<jk>new</jk> SpringApplicationBuilder(App.<jk>class</jk>)
				.initializers(<jk>new</jk> JuneauRestInitializer(App.<jk>class</jk>))
				.run(args);
		}

		<jc>// Our top-level servlet.</jc>
		<ja>@Bean</ja>
		<ja>@JuneauRestRoot</ja>
		<jk>public</jk> MyResource getMyResource() {
			<jk>return new</jk> MyResource();
		}
	}
</p>
<p class='bpcode w800'>
	<ja>@RestResource</ja>(
		path=<js>"/myResource"</js>
	)
	<jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet {...}
</p>

<p>
	In this case, the servlet will get registered using the path defined on the resource class.
</p>

<h5 class='topic'>Path variables</h5>
<p>
	The path can contain variables that get resolved to {@link oaj.http.annotation.Path @Path} parameters
	or access through the {@link oajr.RestRequest#getPathMatch()} method.
</p>
<h5 class='figure'>Example:</h5>
<p class='bpcode'>
	<ja>@RestResource</ja>(
		path=<js>"/myResource/{foo}/{bar}"</js>
	)
	<jk>public class</jk> MyResource <jk>extends</jk> BasicRestServlet {

		<ja>@RestMethod</ja>(
			path=<js>"/{baz}"</js>
		)
		<jk>public void</jk> String doX(<ja>@Path</ja> String foo, <ja>@Path</ja> <jk>int</jk> bar, <ja>@Path</ja> MyPojo baz) {
			...
		}
	}
</p>
<p>
	Variables can be used on either top-level or child resources and can be defined on multiple levels.
</p>
<div class='info'>
	All variables in the path must be specified or else the target will not resolve and a <c>404</c> will result.
</div>
<p>
	When variables are used on a path of a top-level resource deployed as a Spring bean in a Spring Boot application,
	the first part of the URL must be a literal which will be used as the servlet path of the registered servlet.
</p>