{8.1.0-updated} 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:

@Rest( // 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" ) ) @JsonSchemaConfig( // Add descriptions to the following types when not specified: addDescriptionsTo="bean,collection,array,map,enum", // Add x-example to the following types: addExamplesTo="bean,collection,array,map", // Don't generate schema information on the Swagger bean itself or HTML beans. ignoreTypes="Swagger,org.apache.juneau.dto.html5.*", // Use $ref references for bean definitions to reduce duplication in Swagger. useBeanDefs="true" ) @BeanConfig( // When parsing generated beans, ignore unknown properties that may only exist as getters and not setters. ignoreUnknownBeanProperties="true", // POJO swaps to apply to all serializers/parsers on this method. pojoSwaps={ // Use the SwaggerUI swap when rendering Swagger beans. // This is a per-media-type swap that only applies to text/html requests. SwaggerUI.class } ) 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.

@Rest( // 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 }, // HTML-page specific settings htmldoc=@HtmlDoc( // Default page header contents. header={ "<h1>$R{resourceTitle}</h1>", // Use @Rest(title) "<h2>$R{methodSummary,resourceDescription}</h2>", // Use either @RestMethod(summary) or @Rest(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}"} ) @SerializerConfig( // Enable automatic resolution of URI objects to root-relative values. uriResolution="ROOT_RELATIVE" ) 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 @Rest 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.