BasicRestServlet
The {@link oajr.BasicRestServlet} class is a subclass of {@link oajr.RestServlet}
preconfigured with the following:
- A default set of serializers and parsers (pretty much all of them except for the RDF ones).
- Some basic HTML boilerplate for the HTML representation of your POJOs.
- Support for auto-generated Swagger documentation through OPTIONS page requests.
- Configuration of default CSS stylesheets.
- Default contents for HTML views.
The contents of the class is shown below.
You should notice that very little code is being used and everything is configurable through
annotations:
@RestResource(
// Allow OPTIONS requests to be simulated using ?method=OPTIONS query parameter.
allowedMethodParams="OPTIONS",
// HTML-page specific settings.
htmldoc=@HtmlDoc(
// Basic page navigation links.
navlinks={
"up: request:/..",
"options: servlet:/?method=OPTIONS"
}
)
)
public abstract class BasicRestServlet extends RestServlet implements BasicRestConfig {
/**
* [OPTIONS /*] - Show resource options.
*
* @param req The HTTP request.
* @return A bean containing the contents for the OPTIONS page.
*/
@RestMethod(name=OPTIONS, path="/*",
summary="Swagger documentation",
description="Swagger documentation for this resource.",
htmldoc=@HtmlDoc(
// Override the nav links for the swagger page.
navlinks={
"back: servlet:/",
"json: servlet:/?method=OPTIONS&Accept=text/json&plainText=true"
},
// Never show aside contents of page inherited from class.
aside="NONE"
),
// POJO swaps to apply to all serializers/parsers.
pojoSwaps={
// Use the SwaggerUI swap when rendering Swagger beans.
SwaggerUI.class
},
// Properties to apply to all serializers/parsers and REST-specific API objects.
properties={
// Add descriptions to the following types when not specified:
@Property(name=JSONSCHEMA_addDescriptionsTo, value="bean,collection,array,map,enum"),
// Automatically add examples to the following types:
@Property(name=JSONSCHEMA_addExamplesTo, value="bean,collection,array,map"),
// Don't generate schema information on the Swagger bean itself or HTML beans.
@Property(name=JSONSCHEMA_ignoreTypes, value="Swagger,org.apache.juneau.dto.html5.*")
},
// Shortcut for boolean properties.
flags={
// Use $ref references for bean definitions to reduce duplication in Swagger.
JSONSCHEMA_useBeanDefs
}
)
public Swagger getOptions(RestRequest req) {
// Localized Swagger for this resource is available through the RestRequest object.
return req.getSwagger();
}
}
Additional annotations are pulled in from the {@link oajr.BasicRestConfig} interface which simply
exists to define a common set of annotations.
Notice that it has no code at all.
@RestResource(
// Default serializers for all Java methods in the class.
serializers={
HtmlDocSerializer.class,
HtmlStrippedDocSerializer.class,
HtmlSchemaDocSerializer.class,
JsonSerializer.class,
JsonSerializer.Simple.class,
JsonSchemaSerializer.class,
XmlDocSerializer.class,
XmlSchemaDocSerializer.class,
UonSerializer.class,
UrlEncodingSerializer.class,
MsgPackSerializer.class,
SoapXmlSerializer.class,
PlainTextSerializer.class
},
// Default parsers for all Java methods in the class.
parsers={
JsonParser.class,
JsonParser.Simple.class,
XmlParser.class,
HtmlParser.class,
UonParser.class,
UrlEncodingParser.class,
MsgPackParser.class,
PlainTextParser.class
},
// Properties to apply to all serializers/parsers and REST-specific API objects.
properties={
// Enable automatic resolution of URI objects to root-relative values.
@Property(name=SERIALIZER_uriResolution, value="ROOT_RELATIVE")
},
// HTML-page specific settings
htmldoc=@HtmlDoc(
// Default page header contents.
header={
"<h1>$R{resourceTitle}</h1>", // Use @RestResource(title)
"<h2>$R{methodSummary,resourceDescription}</h2>", // Use either @RestMethod(summary) or @RestResource(description)
"$C{REST/header}" // Extra header HTML defined in external config file.
},
// Basic page navigation links.
navlinks={
"up: request:/.."
},
// Default stylesheet to use for the page.
// Can be overridden from external config file.
// Default is DevOps look-and-feel (aka Depression look-and-feel).
stylesheet="$C{REST/theme,servlet:/htdocs/themes/devops.css}",
// Default contents to add to the <head> section of the HTML page.
// Use it to add a favicon link to the page.
head={
"<link rel='icon' href='$U{$C{REST/favicon}}'/>"
},
// No default page footer contents.
// Can be overridden from external config file.
footer="$C{REST/footer}",
// By default, table cell contents should not wrap.
nowrap="true"
),
// Optional external configuration file.
config="$S{juneau.configFile}",
// These are static files that are served up by the servlet under the specified sub-paths.
// For example, "/servletPath/htdocs/javadoc.css" resolves to the file "[servlet-package]/htdocs/javadoc.css"
// By default, we define static files through the external configuration file.
staticFiles={"$C{REST/staticFiles}"}
)
public interface BasicRestConfig {}
Your top-level resource will simply extend from this class, as shown in the Hello World example
from a couple sections back.
It's important to notice that the @RestResource annotation is inheritable and overridable from parent
class and interfaces.
They'll all get merged into a single set of annotation values for the resource class.
Not shown but equally important is that all of the annotations shown have programmatic equivalents via the {@link oajr.RestContextBuilder} class
which can be manipulated during servlet initialization.
(As a general rule, all annotations throughout Juneau have programmatic equivalents.)
There's a lot going on in this class.
But not to worry, the details will be described later.