Predefined Helper Beans
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.ResourceDescription}
- {@link oajr.helper.ResourceDescriptions}
- {@link oajr.helper.SeeOtherRoot}
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:
@Rest
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:
@Rest(
...
children={
HelloWorldResource.class,
PetStoreResource.class,
DtoExamples.class,
PhotosResource.class,
SqlQueryResource.class,
ConfigResource.class,
LogsResource.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.