Package org.apache.juneau.rest.server.servlet

Class RestServlet

java.lang.Object
jakarta.servlet.GenericServlet
jakarta.servlet.http.HttpServlet
org.apache.juneau.rest.server.servlet.RestServlet
All Implemented Interfaces:
jakarta.servlet.Servlet, jakarta.servlet.ServletConfig, Serializable
Direct Known Subclasses:
AdminServlet, BasicRestServlet, FaviconServlet, LoadConfigResource, SpringRestServlet, StaticFilesServlet, VersionServlet, ViewServlet
public abstract class RestServlet extends jakarta.servlet.http.HttpServlet
Servlet implementation of a REST resource.

The RestServlet class is the entry point for your REST resources. It extends directly from HttpServlet and is deployed like any other servlet.

When the servlet init() method is called, it triggers the code to find and process the @Rest annotations on that class and all child classes. These get constructed into a RestContext object that holds all the configuration information about your resource in a read-only object.

Notes:
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    RestServlet.Builder<R extends RestServlet,SELF extends RestServlet.Builder<R,SELF>>
    Fluent builder for programmatically configuring a RestServlet subclass.
    static final class 
    RestServlet.DefaultBuilder<R extends RestServlet>
    Concrete default leaf builder returned by builder(Class) for the common (non-subclassed) case, so callers are not forced to spell the SELF type parameter.

  • Field Summary

    Fields inherited from class jakarta.servlet.http.HttpServlet

    LEGACY_DO_HEAD

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    RestServlet()
    Default constructor.
    protected
    RestServlet(RestBuilder<?> builder)
    Builder-injection constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <R extends RestServlet>
    RestServlet.DefaultBuilder<R>
    builder(Class<R> type)
    Creates a new fluent builder for programmatically configuring an instance of the specified resource type.
    RestAuthenticator
    createAuthenticator(BeanStore beanStore)
    Returns the resource-level authenticator for this servlet, or null to fall through to the @Rest(authenticator=...) annotation / registered bean / @Bean factory method.
    void
    destroy()
     
    protected void
    doLog(Level level, Throwable cause, Supplier<String> msg)
    Main logger method.
    RestContext
    getContext()
    Returns the read-only context object that contains all the configuration information about this resource.
    String
    getPath()
    Returns the path for this resource as defined by the @Rest(path) annotation or RestContext.Builder.path(String) method concatenated with those on all parent classes.
    Object
    getPaths()
    Returns the runtime-overridden top-level mount paths for this resource.
    RestRequest
    getRequest()
    Returns the current thread-local HTTP request.
    RestResponse
    getResponse()
    Returns the current thread-local HTTP response.
    RestBuilder<?>
    getRestBuilder()
    Returns the programmatic configuration builder stashed on this resource, or null if none.
    void
    init(jakarta.servlet.ServletConfig servletConfig)
     
    void
    log(Level level, String msg, Object... args)
    Log a message.
    void
    log(Level level, Throwable cause, String msg, Object... args)
    Log a message.
    void
    service(jakarta.servlet.http.HttpServletRequest r1, jakarta.servlet.http.HttpServletResponse r2)
    The main service method.
    protected void
    setContext(RestContext context)
    Sets the context object for this servlet.

    Methods inherited from class jakarta.servlet.http.HttpServlet

    doDelete, doGet, doHead, doOptions, doPatch, doPost, doPut, doTrace, getLastModified, isSensitiveHeader, service

    Methods inherited from class jakarta.servlet.GenericServlet

    getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • RestServlet

      protected RestServlet()
      Default constructor.

    • RestServlet

      protected RestServlet(RestBuilder<?> builder)
      Builder-injection constructor.
      Parameters:
      builder - The programmatic configuration builder. May be null.

  • Method Details

    • getRestBuilder

      public RestBuilder<?> getRestBuilder()
      Returns the programmatic configuration builder stashed on this resource, or null if none.
      Returns:
      The stashed builder, or null if none was injected.
      Since:
      10.0.0

    • builder

      public static <R extends RestServlet> RestServlet.DefaultBuilder<R> builder(Class<R> type)
      Creates a new fluent builder for programmatically configuring an instance of the specified resource type.

      Builder-supplied values take precedence over the resource class's own @Rest annotation values.

      Type Parameters:
      R - The resource type.
      Parameters:
      type - The resource type to build. Must not be null.
      Returns:
      A new builder.
      Since:
      10.0.0

    • createAuthenticator

      public RestAuthenticator createAuthenticator(BeanStore beanStore)
      Returns the resource-level authenticator for this servlet, or null to fall through to the @Rest(authenticator=...) annotation / registered bean / @Bean factory method.

      This is the lowest-precedence rung in the RestAuthenticator resolution chain (see design spec §5.3). Subclasses can override it to supply an authenticator programmatically.

      Parameters:
      beanStore - The bean store for dependency resolution.
      Returns:
      The authenticator, or null (the default).
      Since:
      10.0.0

    • destroy

      public void destroy()
      Specified by:
      destroy in interface jakarta.servlet.Servlet
      Overrides:
      destroy in class jakarta.servlet.GenericServlet

    • getContext

      public RestContext getContext()
      Returns the read-only context object that contains all the configuration information about this resource.

      This object is null during the call to init(ServletConfig) but is populated by the time GenericServlet.init() is called.

      Resource classes that don't extend from RestServlet can add the following method to their class to get access to this context object:

      public void init(RestServletContext context) throws Exception;

      Returns:
      The context information on this servlet.

    • getPath

      public String getPath()
      Returns the path for this resource as defined by the @Rest(path) annotation or RestContext.Builder.path(String) method concatenated with those on all parent classes.
      Returns:
      The path defined on this servlet, or an empty string if not specified.

    • getPaths

      public Object getPaths()
      Returns the runtime-overridden top-level mount paths for this resource.

      Subclasses can override this method to substitute the @Rest(paths) annotation defaults at construction time. This is the "getter" rung in the runtime-override resolution chain documented on RestContext.getPaths():

      1. Programmatic (RestContext.Builder.paths(String...)) — highest precedence.
      2. This getPaths() getter (when non-null).
      3. @Rest(paths={...}) annotation default (SVL-resolved per element, comma-split) — lowest precedence.
      Accepted return shapes:
      • null — no override; resolution falls through to the @Rest(paths=...) annotation default.
      • String — a single path or a comma-delimited list, e.g. "/healthz,/readyz".
      • String[] — each element may itself be a comma-delimited list.
      • Collection, List, Set, Iterable, or Stream of any of the above (nested mixes are recursively flattened).
      • Primitive arrays (boxed during flattening).

      Non-String leaves are coerced via String.valueOf(Object). Each leaf string then runs through the same per-element pipeline used for @Rest(paths=...) annotation elements: SVL is applied via the bean-store-backed VarResolverSession (so $C{key} consults the live Config, $E{NAME,default} and $S{prop,default} resolve through the bootstrap variable catalog), and the post-SVL value is comma-split with each piece trimmed and empty pieces dropped.

      Notes:
      • Returning null (the default) means "inherit annotation" — the next rung resolves.
      • Returning new String[0], an empty collection, an empty string, or a blank string means "explicitly clear" — no top-level mounts.
      • The scalar accessor getPath() remains orthogonal to this method — the singular @Rest(path=...) attribute has its own resolution chain and is unaffected.
      Returns:
      The runtime-overridden mount paths in any accepted shape, or null to inherit the annotation default.
      Since:
      10.0.0

    • getRequest

      public RestRequest getRequest()
      Returns the current thread-local HTTP request.
      Returns:
      The current thread-local HTTP request, or null if it wasn't created.

    • getResponse

      public RestResponse getResponse()
      Returns the current thread-local HTTP response.
      Returns:
      The current thread-local HTTP response, or null if it wasn't created.

    • init

      public void init(jakarta.servlet.ServletConfig servletConfig) throws jakarta.servlet.ServletException
      Specified by:
      init in interface jakarta.servlet.Servlet
      Overrides:
      init in class jakarta.servlet.http.HttpServlet
      Throws:
      jakarta.servlet.ServletException

    • log

      public void log(Level level, String msg, Object... args)
      Log a message.

      Subclasses can intercept the handling of these messages by overriding doLog(Level, Throwable, Supplier).

      Parameters:
      level - The log level.
      msg - The message to log.
      args - Optional String.format-style arguments.

    • log

      public void log(Level level, Throwable cause, String msg, Object... args)
      Log a message.

      Subclasses can intercept the handling of these messages by overriding doLog(Level, Throwable, Supplier).

      Parameters:
      level - The log level.
      cause - The cause.
      msg - The message to log.
      args - Optional String.format-style arguments.

    • service

      public void service(jakarta.servlet.http.HttpServletRequest r1, jakarta.servlet.http.HttpServletResponse r2) throws jakarta.servlet.ServletException, InternalServerError, IOException
      The main service method.

      Subclasses can optionally override this method if they want to tailor the behavior of requests.

      Overrides:
      service in class jakarta.servlet.http.HttpServlet
      Throws:
      jakarta.servlet.ServletException
      InternalServerError
      IOException

    • doLog

      protected void doLog(Level level, Throwable cause, Supplier<String> msg)
      Main logger method.

      The default behavior logs a message to the Java logger of the class name.

      Subclasses can override this method to implement their own logger handling.

      Parameters:
      level - The log level.
      cause - Optional throwable.
      msg - The message to log.

    • setContext

      protected void setContext(RestContext context) throws jakarta.servlet.ServletException
      Sets the context object for this servlet.

      This method is effectively a no-op if init(ServletConfig) has already been called.

      Parameters:
      context - Sets the context object on this servlet. Must not be null.
      Throws:
      jakarta.servlet.ServletException - If error occurred during initialization.