The {@link oajr.helper} package contains several predefined beans to help when constructing REST interfaces.

• {@link oajr.helper}
  • {@link oajr.helper.BeanDescription}
  • {@link oajr.helper.ChildResourceDescriptions}
  • {@link oajr.helper.ReaderResource}
  • {@link oajr.helper.ReaderResourceBuilder}
  • {@link oajr.helper.ResourceDescription}
  • {@link oajr.helper.ResourceDescriptions}
  • {@link oajr.helper.SeeOtherRoot}
  • {@link oajr.helper.StreamResource}
  • {@link oajr.helper.StreamResourceBuilder}

ResourceDescription, ResourceDescrptions

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:

@Resource public class PredefinedLabelsResource { @RestMethod(name=GET, path="/") public ResourceDescription[] getChildMethods() { return new ResourceDescription[] { new ResourceDescription("beanDescription", "BeanDescription"), new ResourceDescription("htmlLinks", "HtmlLink") }; } }

It get rendered as a table of name/description columns with links to child methods:

The internals of the class show it simply has two bean properties with a link annotation defined on the name property:

public class ResourceDescription { // Renders as hyperlink when serialized as HTML. @Html(link="servlet:/{name}") public String getName() {...} public String getDescription() {...} }

{@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):

@Resource public class PredefinedLabelsResource { @RestMethod(name=GET, path="/") public ResourceDescriptions getChildMethods() { return new ResourceDescriptions() .append("beanDescription", "BeanDescription") .append("htmlLinks", "HtmlLink"); } }

@HtmlLink, LinkString

The {@link oaj.html.annotation.HtmlLink @HtmlLink} annotation can also be useful for rendering custom hyperlinks:

@RestMethod public MyLink[] htmlLinks() { return new MyLink[] { new MyLink("apache", "http://apache.org"), new MyLink("juneau", "http://juneau.apache.org") }; }

@HtmlLink(nameProperty="name", hrefProperty="href") public class MyLink { // Simple bean properties. public String name, href; public MyLink(String name, String href) { this.name = name; this.href = href; } }

The {@link oaj.dto.LinkString LinkString} bean is a predefined @HtmlLink bean provided to simplify specifying actions.
The following is equivalent to above.

@RestMethod public LinkString[] htmlLinks() { return new LinkString[] { new LinkString("apache", "http://apache.org"), new LinkString("juneau", "http://juneau.apache.org") }; }

Both examples render the following consisting of a list of hyperlinks:

In all other languages, it gets serialized as a simple bean with two properties.

BeanDescription

The {@link oajr.helper.BeanDescription} class provides a simple view of a bean and it's properties.

@RestMethod(name=GET, path="/beanDescription") public BeanDescription getBeanDescription() { return new BeanDescription(Person.class); }

This example renders the following:

ChildResourceDescriptions

The {@link oajr.helper.ChildResourceDescriptions} is a convenience bean for generating a table of child resources.

The {@link oajr.BasicRestServletGroup} class uses this to generate router pages:

@RestResource public abstract class BasicRestServletGroup extends BasicRestServlet { @RestMethod(name=GET, path="/", summary="Navigation page") public ChildResourceDescriptions getChildren(RestRequest req) throws Exception { return new ChildResourceDescriptions(req); } }

Note that all it requires is a {@link oajr.RestRequest} object and it will generate a router page using reflection against the resource class.

For example, the RootResources page in the REST examples renders the child resources attached to the root resource:

The RootResources page consists of the following and extends from the {@link oajr.BasicRestServletGroup} class:

@RestResource( ... children={ HelloWorldResource.class, PetStoreResource.class, SystemPropertiesResource.class, MethodExampleResource.class, RequestEchoResource.class, AddressBookResource.class, SampleRemoteInterfaceServlet.class, DtoExamples.class, PhotosResource.class, SqlQueryResource.class, CodeFormatterResource.class, UrlEncodedFormResource.class, TempDirResource.class, ConfigResource.class, LogsResource.class, DockerRegistryResource.class, DebugResource.class, ShutdownResource.class } ) public class RootResources extends BasicRestServletJenaGroup {}

SeeOtherRoot

The {@link oajr.helper.SeeOtherRoot} class can be used to redirect to the root URI of a resource class.

@RestMethod(name="POST", path="/pets") public SeeOtherRoot addPet(@Body Pet pet) { addPet(Pet); // Redirects to the servlet root URL. return SeeOtherRoot.INSTANCE; }

The runtime behavior is the same as the following:

@RestMethod(name="POST", path="/pets") public SeeOther addPet(@Body Pet pet) { addPet(Pet); // Redirects to the servlet root URL. return new SeeOther(URI.create("servlet:/")); }

One distinction is that the former defines the description "Redirect to servlet root" in the generated Swagger documentation.