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 these Basic* classes:

HttpServletRestServletBasicRestServlet implements BasicRestOperations, BasicUniversalConfigBasicRestServletGroup implements BasicGroupOperationsSpringRestServletBasicSpringRestServlet implements BasicRestOperations, BasicUniversalConfigBasicSpringRestServletGroup implements BasicGroupOperationsRestObjectBasicRestObject implements BasicRestOperations, BasicJsonConfigBasicRestObjectGroup implements BasicGroupOperations

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

RestServletLogging methods:log(Level,String,Object...)log(Level,Throwable,String,Object...)log(String)log(String,Throwable)Other methods:getContext()getPath()getRequest()getResponse()

The Basic* classes implement the BasicRestOperations interface which defines common endpoints for swagger documentation, statistics, and serving static files:

public interface BasicRestOperations {

    @RestGet(path="/api/*")
    public Swagger getSwagger(RestRequest req);

    @RestGet(path="/htdocs/*")
    public HttpResource getHtdoc(@Path String path, Locale locale);

    @RestGet(path="favicon.ico")
    public HttpResource getFavIcon();

    @RestGet(path="/stats")
    public RestContextStats getStats(RestRequest req);

    @RestOp(method=ANY, path="/error")
    public void error();
}

The Basic* classes also implement BasicJsonConfig interface which provides basic JSON 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.

BasicJsonConfigBasicJsonHtmlConfigBasicJson5ConfigBasicOpenApiConfigBasicUniversalConfig

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 *Group classes implement the BasicGroupOperations interface which provides an additional REST endpoint for listing and navigating child resources:

public interface BasicGroupOperations {

    @RestGet(path="/")
    public ChildResourceDescriptions getChildren(RestRequest req);
}

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 *Object* classes provide the same functionality as the servlet classes but do not extend from HttpServlet. This becomes 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. This is less important in standard servlet containers that don't auto-deploy servlets. In those environments, you can also use servlet classes for child resources.

The following is a breakdown of which classes you will use in different cases:

Top level resources in a servlet container:

BasicRestServletBasicRestServletGroup

Top level resources in a Spring Boot environment:

BasicSpringRestServletBasicSpringRestServletGroup

Child resources:

BasicRestObjectBasicRestObjectGroup