juneau-doc/docs/Topics/06.juneau-rest-server/06.RestMethod/17.PredefinedHelperBeans.html - juneau - Git at Google

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