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 {@link oajr.servlet.RestServlet} class provides all the logic for starting up your REST
application when the servlet container calls {@link oajr.servlet.RestServlet#init(ServletConfig) 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 {@link oajr.servlet.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:
- {@link jakarta.servlet.http.HttpServlet}
- {@link oajr.servlet.RestServlet}
- {@link oajr.servlet.BasicRestServlet} implements {@link oajr.servlet.BasicRestOperations}, {@link oajr.config.BasicUniversalConfig}
- {@link oajr.servlet.BasicRestServletGroup} implements {@link oajr.servlet.BasicGroupOperations}
- {@link oajr.springboot.SpringRestServlet}
- {@link oajr.springboot.BasicSpringRestServlet} implements {@link oajr.servlet.BasicRestOperations}, {@link oajr.config.BasicUniversalConfig}
- {@link oajr.springboot.BasicSpringRestServletGroup} implements {@link oajr.servlet.BasicGroupOperations}
- {@link oajr.servlet.RestObject}
- {@link oajr.servlet.BasicRestObject} implements {@link oajr.servlet.BasicRestOperations}, {@link oajr.config.BasicJsonConfig}
- {@link oajr.servlet.BasicRestObjectGroup} implements {@link oajr.servlet.BasicGroupOperations}
The {@link oajr.servlet.RestServlet}
class itself is not configured with any serializers or parsers. However, it does
provide several convenience methods to be aware of:
- {@link oajr.servlet.RestServlet}
- Logging methods:
- {@link oajr.servlet.RestServlet#log(Level,String,Object...) log(Level,String,Object...)}
- {@link oajr.servlet.RestServlet#log(Level,Throwable,String,Object...) log(Level,Throwable,String,Object...)}
- {@link oajr.servlet.RestServlet#log(String) log(String)}
- {@link oajr.servlet.RestServlet#log(String,Throwable) log(String,Throwable)}
- Other methods:
- {@link oajr.servlet.RestServlet#getContext() getContext()}
- {@link oajr.servlet.RestServlet#getPath() getPath()}
- {@link oajr.servlet.RestServlet#getRequest() getRequest()}
- {@link oajr.servlet.RestServlet#getResponse() getResponse()}
The Basic* classes implement the {@link oajr.servlet.BasicRestOperations} interface
which defines common endpoints for swagger documentation, statistics, and serving static files:
| public interface BasicRestOperations {
|
| @RestGet(path="/api/*")
| public {@link oaj.dto.swagger.Swagger} {@link oajr.servlet.BasicRestOperations#getSwagger(RestRequest) getSwagger}({@link oajr.RestRequest} req);
|
| @RestGet(path="/htdocs/*")
| public {@link oaj.http.resource.HttpResource} {@link oajr.servlet.BasicRestOperations#getHtdoc(String,Locale) getHtdoc}(@Path String path, Locale locale);
|
| @RestGet(path="favicon.ico")
| public {@link oaj.http.resource.HttpResource} {@link oajr.servlet.BasicRestOperations#getFavIcon() getFavIcon}();
|
| @RestGet(path="/stats")
| public {@link oajr.stats.RestContextStats} {@link oajr.servlet.BasicRestOperations#getStats(RestRequest) getStats}({@link oajr.RestRequest} req);
|
| @RestOp(method=ANY, path="/error")
| public void {@link oajr.servlet.BasicRestOperations#error() error}();
| }
The Basic* classes also implement {@link oajr.config.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.
- {@link oajr.config.BasicJsonConfig}
- {@link oajr.config.BasicJsonHtmlConfig}
- {@link oajr.config.BasicJson5Config}
- {@link oajr.config.BasicOpenApiConfig}
- {@link oajr.config.BasicUniversalConfig}
For example, if you want to provide a resource that supports all languages in Juneau,
simply add the {@link oajr.config.BasicUniversalConfig} interface like so:
| @Rest(...)
| public class MyResource extends RestServlet implements BasicUniversalConfig {
| ...
| }
The *Group classes implement the {@link oajr.servlet.BasicGroupOperations} interface which provides an additional REST endpoint for listing and navigating child resources:
| public interface BasicGroupOperations {
|
| @RestGet(path="/")
| public {@link oajr.beans.ChildResourceDescriptions} {@link oajr.servlet.BasicGroupOperations#getChildren(RestRequest) getChildren}({@link oajr.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 {@link jakarta.servlet.http.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:
- {@link oajr.servlet.BasicRestServlet}
- {@link oajr.servlet.BasicRestServletGroup}
- Top level resources in a Spring Boot environment:
- {@link oajr.springboot.BasicSpringRestServlet}
- {@link oajr.springboot.BasicSpringRestServletGroup}
- Child resources:
- {@link oajr.servlet.BasicRestObject}
- {@link oajr.servlet.BasicRestObjectGroup}