| <!-- |
| /*************************************************************************************************************************** |
| * 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. |
| ***************************************************************************************************************************/ |
| --> |
| |
| {8.1.0-new, 8.1.2-updated} |
| @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> |
| |