Predefined Classes

The following example represents the bare-minimum needed for deploying a top-level REST endpoint with basic JSON marshalling support:

@Rest(
    path="/mypath",
    serializers=JsonSerializer.class,
    parsers=JsonParser.class
)
public class MyResource extends RestServlet {

    @RestGet(path="/")
    public Object getPojo() {
        ...
    }
}

The RestServlet class provides all the logic for starting up your REST application when the servlet container calls init(ServletConfig). On startup, it scans your class for annotations and sets up all of your serializers and parsers. It then does this recursively for all child resources.

Users will typically not extend directly from RestServlet. Instead, several classes are provided by the framework to provide additional functionality and to handle different use-cases.

Users will typically extend from one of the Basic* classes in one of three families: the servlet family, the resource family, and the Spring Boot family. Cross-cutting endpoints (swagger docs, static files, stats, error, favicon, navigation) are supplied by single-responsibility mixin classes rather than by interfaces.

Servlet family

The servlet family extends HttpServlet and is the standard choice for top-level resources deployed in a servlet container (standalone Jetty, embedded Tomcat, Spring Boot via ServletRegistrationBean).

HttpServlet

RestServlet

BasicRestServlet - Full-featured servlet with universal marshalling and op-mixin endpoints

BasicRestServletGroup - Adds child-resource navigation (GET / via NavigationMixin)

Resource family

The resource family does not extend HttpServlet. Use these for child resources mounted under a servlet-family parent, or in Spring Boot environments where you want to declare child resources as Spring beans without Spring Boot auto-detecting them as top-level servlets.

RestResource

BasicRestResource - Full-featured resource with universal marshalling and op-mixin endpoints

BasicRestResourceGroup - Adds child-resource navigation

Spring Boot family

The Spring Boot family extends the servlet family but hooks into the Spring ApplicationContext to resolve child resources and helper classes as Spring beans.

SpringRestServlet

BasicSpringRestServlet - Spring-aware equivalent of BasicRestServlet

BasicSpringRestServletGroup - Spring-aware equivalent of BasicRestServletGroup

Mixin family

Cross-cutting endpoints are contributed by single-responsibility mixin classes in org.apache.juneau.rest.server.ops. Mixins are composed into a host via @Rest(mixins=...). BasicRestServlet composes all of them by default; you can opt out via @Rest(noInherit={"mixins"}) and re-declare only what you need.

RestMixin

HtdocMixin - GET /htdocs/* static-file endpoint

StatsMixin - GET /stats timing-statistics endpoint

NavigationMixin - GET / child-resource navigation page (used by *Group classes)

ErrorMixin - * /error error-redirect endpoint

The RestServlet class itself is not configured with any serializers or parsers. However, it does provide several convenience methods to be aware of:

RestServlet

Logging methods:

log(Level,String,Object...)

log(Level,Throwable,String,Object...)

log(String)

log(String,Throwable)

Other methods:

The Basic* classes compose the op-mixin endpoints via @Rest(mixins=...). BasicRestServlet declares:

@Rest(mixins={SwaggerUiMixin.class, RedocMixin.class, ErrorMixin.class, HtdocMixin.class, StatsMixin.class, FaviconMixin.class})
public abstract class BasicRestServlet extends RestServlet implements BasicUniversalConfig { ... }

BasicRestServletGroup adds NavigationMixin on top:

@Rest(mixins={NavigationMixin.class})
public abstract class BasicRestServletGroup extends BasicRestServlet { ... }

The Basic* classes also implement BasicJsonConfig (or BasicUniversalConfig on BasicRestServlet) which provides marshalling support. Other config interfaces are available as well to quickly provide different types of marshalling support. Note that these interfaces do not define any methods but rather simply provide a set of commonly-used annotations so that you don't need to define them on all your classes.

For example, if you want to provide a resource that supports all languages in Juneau, simply add the BasicUniversalConfig interface like so:

@Rest(...)
public class MyResource extends RestServlet implements BasicUniversalConfig {
    ...
}

The *Spring* classes are meant to be used in Spring Boot environments so that you can take full advantage of the Spring Framework for injecting dependencies on child resources and helper classes.

The resource family (BasicRestResource, BasicRestResourceGroup) provides the same functionality as the servlet classes but does not extend from HttpServlet. This is important in Spring Boot environments where you may want to define child resources as Spring beans but don't want Spring Boot to auto-detect them as servlets to be deployed as top-level resources.

Choosing the right base class

Use case	Base class	Notes
Single REST resource (non-Spring)	`BasicRestServlet` or `BasicRestResource`	Use when you don't need Spring bean injection
Single REST resource (Spring Boot)	`BasicSpringRestServlet`	Enables `@Autowired` in child resources
Router page (non-Spring)	`BasicRestServletGroup`	Mounts child resources
Router page (Spring Boot)	`BasicSpringRestServletGroup`	Mounts child resources with Spring bean resolution