| <!-- |
| /*************************************************************************************************************************** |
| * 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. |
| ***************************************************************************************************************************/ |
| --> |
| |
| Predefined Helper Beans |
| |
| <p> |
| The {@link oajr.helper} package contains several predefined beans to help when constructing |
| REST interfaces. |
| </p> |
| <ul class='javatree'> |
| <li class='jp'>{@link oajr.helper} |
| <ul> |
| <li class='jc'>{@link oajr.helper.BeanDescription} |
| <li class='jc'>{@link oajr.helper.ChildResourceDescriptions} |
| <li class='jc'>{@link oajr.helper.ResourceDescription} |
| <li class='jc'>{@link oajr.helper.ResourceDescriptions} |
| <li class='jc'>{@link oajr.helper.SeeOtherRoot} |
| </ul> |
| </ul> |
| |
| <h5 class='topic'>ResourceDescription, ResourceDescrptions</h5> |
| <p> |
| The {@link oajr.helper.ResourceDescription} class is a bean with name/description |
| properties for labeling and linking to child resources. |
| The following examples is pulled from the REST examples: |
| </p> |
| <p class='bpcode w800'> |
| <ja>@Resource</ja> |
| <jk>public class</jk> PredefinedLabelsResource { |
| |
| <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>) |
| <jk>public</jk> ResourceDescription[] getChildMethods() { |
| <jk>return new</jk> ResourceDescription[] { |
| <jk>new</jk> ResourceDescription(<js>"beanDescription"</js>, <js>"BeanDescription"</js>), |
| <jk>new</jk> ResourceDescription(<js>"htmlLinks"</js>, <js>"HtmlLink"</js>) |
| }; |
| } |
| } |
| </p> |
| <p> |
| It get rendered as a table of name/description columns with links to child methods: |
| </p> |
| <img class='bordered' src='doc-files/juneau-rest-server.PredefinedLabelBeans.1.png' style='width:240px'/> |
| <p> |
| The internals of the class show it simply has two bean properties with a link annotation |
| defined on the name property: |
| </p> |
| <p class='bpcode w800'> |
| <jk>public class</jk> ResourceDescription { |
| |
| <jc>// Renders as hyperlink when serialized as HTML.</jc> |
| <ja>@Html</ja>(link=<js>"servlet:/{name}"</js>) |
| <jk>public</jk> String getName() {...} |
| |
| <jk>public</jk> String getDescription() {...} |
| } |
| </p> |
| <p> |
| {@link oajr.helper.ResourceDescriptions} is a convenience class for doing the same. |
| The example above can also be written as follows (which you'll notice is more concise): |
| </p> |
| <p class='bpcode w800'> |
| <ja>@Resource</ja> |
| <jk>public class</jk> PredefinedLabelsResource { |
| |
| <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>) |
| <jk>public</jk> ResourceDescriptions getChildMethods() { |
| <jk>return new</jk> ResourceDescriptions() |
| .append(<js>"beanDescription"</js>, <js>"BeanDescription"</js>) |
| .append(<js>"htmlLinks"</js>, <js>"HtmlLink"</js>); |
| } |
| } |
| </p> |
| <h5 class='topic'>@HtmlLink, LinkString</h5> |
| <p> |
| The {@link oaj.html.annotation.HtmlLink @HtmlLink} annotation can also be useful |
| for rendering custom hyperlinks: |
| </p> |
| <p class='bpcode w800'> |
| <ja>@RestMethod</ja> |
| <jk>public</jk> MyLink[] htmlLinks() { |
| <jk>return new</jk> MyLink[] { |
| <jk>new</jk> MyLink(<js>"apache"</js>, <js>"http://apache.org"</js>), |
| <jk>new</jk> MyLink(<js>"juneau"</js>, <js>"http://juneau.apache.org"</js>) |
| }; |
| } |
| </p> |
| <p class='bpcode w800'> |
| <ja>@HtmlLink</ja>(nameProperty=<js>"name"</js>, hrefProperty=<js>"href"</js>) |
| <jk>public class</jk> MyLink { |
| |
| <jc>// Simple bean properties.</jc> |
| <jk>public</jk> String <jf>name</jf>, <jf>href</jf>; |
| |
| <jk>public</jk> MyLink(String name, String href) { |
| <jk>this</jk>.<jf>name</jf> = name; |
| <jk>this</jk>.<jf>href</jf> = href; |
| } |
| } |
| </p> |
| <p> |
| The {@link oaj.dto.LinkString LinkString} bean is a predefined <ja>@HtmlLink</ja> bean provided |
| to simplify specifying actions. |
| The following is equivalent to above. |
| </p> |
| <p class='bpcode w800'> |
| <ja>@RestMethod</ja> |
| <jk>public</jk> LinkString[] htmlLinks() { |
| <jk>return new</jk> LinkString[] { |
| <jk>new</jk> LinkString(<js>"apache"</js>, <js>"http://apache.org"</js>), |
| <jk>new</jk> LinkString(<js>"juneau"</js>, <js>"http://juneau.apache.org"</js>) |
| }; |
| } |
| </p> |
| <p> |
| Both examples render the following consisting of a list of hyperlinks: |
| </p> |
| <img class='bordered' src='doc-files/juneau-rest-server.PredefinedLabelBeans.3.png' style='width:92px'/> |
| <p> |
| In all other languages, it gets serialized as a simple bean with two properties. |
| </p> |
| |
| <h5 class='topic'>BeanDescription</h5> |
| <p> |
| The {@link oajr.helper.BeanDescription} class provides a simple view |
| of a bean and it's properties. |
| </p> |
| <p class='bpcode w800'> |
| <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/beanDescription"</js>) |
| <jk>public</jk> BeanDescription getBeanDescription() { |
| <jk>return new</jk> BeanDescription(Person.<jk>class</jk>); |
| } |
| </p> |
| <p> |
| This example renders the following: |
| </p> |
| <img class='bordered' src='doc-files/juneau-rest-server.PredefinedLabelBeans.2.png' style='width:584px'/> |
| |
| <h5 class='topic'>ChildResourceDescriptions</h5> |
| <p> |
| The {@link oajr.helper.ChildResourceDescriptions} is a convenience bean for generating |
| a table of child resources. |
| </p> |
| <p> |
| The {@link oajr.BasicRestServletGroup} class uses this to generate router pages: |
| </p> |
| <p class='bpcode w800'> |
| <ja>@Rest</ja> |
| <jk>public abstract class</jk> BasicRestServletGroup <jk>extends</jk> BasicRestServlet { |
| |
| <ja>@RestMethod</ja>(name=<jsf>GET</jsf>, path=<js>"/"</js>, summary=<js>"Navigation page"</js>) |
| <jk>public</jk> ChildResourceDescriptions getChildren(RestRequest req) <jk>throws</jk> Exception { |
| <jk>return new</jk> ChildResourceDescriptions(req); |
| } |
| } |
| </p> |
| <p> |
| Note that all it requires is a {@link oajr.RestRequest} object and it will generate a router |
| page using reflection against the resource class. |
| </p> |
| <p> |
| For example, the <c>RootResources</c> page in the REST examples renders the child resources attached to the root resource: |
| </p> |
| <img class='bordered' src='doc-files/juneau-rest-server.PredefinedLabelBeans.4.png' style='width:800px'/> |
| <p> |
| The <c>RootResources</c> page consists of the following and extends from the {@link oajr.BasicRestServletGroup} class: |
| </p> |
| <p class='bpcode w800'> |
| <ja>@Rest</ja>( |
| ... |
| children={ |
| HelloWorldResource.<jk>class</jk>, |
| PetStoreResource.<jk>class</jk>, |
| DtoExamples.<jk>class</jk>, |
| PhotosResource.<jk>class</jk>, |
| SqlQueryResource.<jk>class</jk>, |
| ConfigResource.<jk>class</jk>, |
| LogsResource.<jk>class</jk>, |
| DebugResource.<jk>class</jk>, |
| ShutdownResource.<jk>class</jk> |
| } |
| ) |
| <jk>public class</jk> RootResources <jk>extends</jk> BasicRestServletJenaGroup {} |
| </p> |
| |
| <h5 class='topic'>SeeOtherRoot</h5> |
| <p> |
| The {@link oajr.helper.SeeOtherRoot} class can be used to redirect to the root URI |
| of a resource class. |
| </p> |
| <p class='bpcode w800'> |
| <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>) |
| <jk>public</jk> SeeOtherRoot addPet(<ja>@Body</ja> Pet pet) { |
| <jsm>addPet</jsm>(Pet); |
| |
| <jc>// Redirects to the servlet root URL.</jc> |
| <jk>return</jk> SeeOtherRoot.INSTANCE; |
| } |
| </p> |
| <p> |
| The runtime behavior is the same as the following: |
| </p> |
| <p class='bpcode w800'> |
| <ja>@RestMethod</ja>(name=<js>"POST"</js>, path=<js>"/pets"</js>) |
| <jk>public</jk> SeeOther addPet(<ja>@Body</ja> Pet pet) { |
| <jsm>addPet</jsm>(Pet); |
| |
| <jc>// Redirects to the servlet root URL.</jc> |
| <jk>return new</jk> SeeOther(URI.<jsm>create</jsm>(<js>"servlet:/"</js>)); |
| } |
| </p> |
| <p> |
| One distinction is that the former defines the description <js>"Redirect to servlet root"</js> in the generated Swagger documentation. |
| </p> |