public abstract class RestServlet extends HttpServlet implements RestInfoProvider, RestCallLogger, RestResourceResolver, ResourceFinder
RestInfoProvider.Null
RestCallLogger.Null
RestResourceResolver.Null
ResourceFinder.Null
BASIC, FUZZY
Constructor and Description |
---|
RestServlet() |
Modifier and Type | Method and Description |
---|---|
void |
destroy() |
protected void |
doLog(Level level,
Throwable cause,
Supplier<String> msg)
Main logger method.
|
InputStream |
findResource(Class<?> baseClass,
String name,
Locale locale)
Returns the contents of the resource with the specified name.
|
RestContext |
getContext()
Returns the read-only context object that contains all the configuration information about this resource.
|
String |
getDescription(RestRequest req)
Returns the localized description of the REST resource.
|
String |
getMethodDescription(Method method,
RestRequest req)
Returns the localized description of the specified java method on this servlet.
|
String |
getMethodSummary(Method method,
RestRequest req)
Returns the localized summary of the specified java method.
|
String |
getPath()
Returns the path defined on this servlet if it's defined via
Rest.path() . |
RestContextProperties |
getProperties()
Convenience method for calling
|
RestRequest |
getRequest()
Returns the current HTTP request.
|
RestResponse |
getResponse()
Returns the current HTTP response.
|
RestContextBuilder |
getServletConfig() |
String |
getSiteName(RestRequest req)
Returns the localized site name of the REST resource.
|
Swagger |
getSwagger(RestRequest req)
Returns the localized swagger for the REST resource.
|
String |
getTitle(RestRequest req)
Returns the localized title of the REST resource.
|
void |
init(ServletConfig servletConfig) |
boolean |
isInitialized()
Returns
getContext() returns a value. |
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 |
log(RestCallLoggerConfig config,
HttpServletRequest req,
HttpServletResponse res)
Called at the end of a servlet request to log the request.
|
void |
log(String msg)
Log a message at
Level.INFO level. |
void |
log(String msg,
Throwable cause)
Log a message.
|
void |
onDestroy(RestContext context)
Method that gets called during servlet destroy.
|
void |
onEndCall(HttpServletRequest req,
HttpServletResponse res)
Method that gets called right before we exit the servlet service method.
|
void |
onInit(RestContextBuilder builder)
Method that gets called during servlet initialization.
|
void |
onPostCall(RestRequest req,
RestResponse res)
Method that gets called immediately after the
|
void |
onPostInit(RestContext context)
Method that gets called immediately after servlet initialization.
|
void |
onPostInitChildFirst(RestContext context)
Identical to
onPostInit(RestContext) except the order of execution is child-resources first. |
void |
onPreCall(RestRequest req,
RestResponse res)
Method that gets called immediately before the
|
void |
onStartCall(HttpServletRequest req,
HttpServletResponse res)
A method that is called immediately after the
|
<T> T |
resolve(Object parent,
Class<T> c,
Object... args)
Resolves the specified class to a resource object.
|
<T> T |
resolve(Object parent,
Class<T> c,
RestContextBuilder builder,
Object... args)
Resolves the specified class to a resource object.
|
void |
service(HttpServletRequest r1,
HttpServletResponse r2)
The main service method.
|
void |
setContext(RestContext context)
Sets the context object for this servlet.
|
RestServlet |
setRestResourceResolver(RestResourceResolver resourceResolver)
Sets the resource resolver to use for this servlet and all child servlets.
|
doDelete, doGet, doHead, doOptions, doPost, doPut, doTrace, getLastModified, service
getInitParameter, getInitParameterNames, getServletContext, getServletInfo, getServletName, init
public RestServlet()
public final void init(ServletConfig servletConfig) throws ServletException
init
in interface Servlet
init
in class GenericServlet
ServletException
public void setContext(RestContext context) throws ServletException
context
- Sets the context object on this servlet.ServletException
- If error occurred during post-initialiation.public boolean isInitialized()
getContext()
returns a value.getContext()
returns a value.public RestServlet setRestResourceResolver(RestResourceResolver resourceResolver)
This method can be called immediately following object construction, but must be called before init(ServletConfig)
is called.
Otherwise calling this method will have no effect.
resourceResolver
- The resolver instance. Can be public String getPath()
Rest.path()
.public RestContextBuilder getServletConfig()
getServletConfig
in interface Servlet
getServletConfig
in class GenericServlet
public RestContext getContext()
This object is 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 RestContextProperties getProperties()
RestContextProperties
.RestContext.getProperties()
public void log(String msg)
Level.INFO
level.
Subclasses can intercept the handling of these messages by overriding doLog(Level, Throwable, Supplier)
.
log
in class GenericServlet
msg
- The message to log.public void log(String msg, Throwable cause)
Subclasses can intercept the handling of these messages by overriding doLog(Level, Throwable, Supplier)
.
log
in class GenericServlet
msg
- The message to log.cause
- The cause.public void log(Level level, String msg, Object... args)
Subclasses can intercept the handling of these messages by overriding doLog(Level, Throwable, Supplier)
.
level
- The log level.msg
- The message to log.args
- Optional MessageFormat
-style arguments.public void log(Level level, Throwable cause, String msg, Object... args)
Subclasses can intercept the handling of these messages by overriding doLog(Level, Throwable, Supplier)
.
level
- The log level.cause
- The cause.msg
- The message to log.args
- Optional MessageFormat
-style arguments.protected void doLog(Level level, Throwable cause, Supplier<String> msg)
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.
level
- The log level.cause
- Optional throwable.msg
- The message to log.public void service(HttpServletRequest r1, HttpServletResponse r2) throws ServletException, InternalServerError, IOException
Subclasses can optionally override this method if they want to tailor the behavior of requests.
service
in class HttpServlet
ServletException
InternalServerError
IOException
public void destroy()
destroy
in interface Servlet
destroy
in class GenericServlet
@RestHook(value=INIT) public void onInit(RestContextBuilder builder) throws Exception
This method is called from within the Servlet.init(ServletConfig)
method after the RestContextBuilder
object has been created and initialized with the annotations defined on the class, but before the
RestContext
object has been created.
An example of this is the
builder
- Context builder which can be used to configure the servlet.Exception
- Any exception thrown will cause servlet to fail startup.@RestHook(value=POST_INIT) public void onPostInit(RestContext context) throws Exception
This method is called from within the Servlet.init(ServletConfig)
method after the RestContext
object has been created.
context
- The initialized context object.Exception
- Any exception thrown will cause servlet to fail startup.@RestHook(value=POST_INIT_CHILD_FIRST) public void onPostInitChildFirst(RestContext context) throws Exception
onPostInit(RestContext)
except the order of execution is child-resources first.
Use this method if you need to perform any kind of initialization on child resources before the parent resource.
This method is called from within the Servlet.init(ServletConfig)
method after the RestContext
object has been created and after the HookEvent.POST_INIT
methods have been called.
The only valid parameter type for this method is RestContext
which can be used to retrieve information
about the servlet.
context
- The initialized context object.Exception
- Any exception thrown will cause servlet to fail startup.@RestHook(value=DESTROY) public void onDestroy(RestContext context) throws Exception
This method is called from within the Servlet.destroy()
.
context
- The initialized context object.Exception
- Any exception thrown will cause stack trace to be printed to @RestHook(value=START_CALL) public void onStartCall(HttpServletRequest req, HttpServletResponse res) throws Exception
Note that you only have access to the raw request and response objects at this point.
HttpExceptions
can be thrown to cause a particular HTTP error status code.
req
- The HTTP servlet request object.res
- The HTTP servlet response object.Exception
- Any exception.@RestHook(value=PRE_CALL) public void onPreCall(RestRequest req, RestResponse res) throws Exception
At this point, the RestRequest
object has been fully initialized, and all RestGuard
and
RestMatcher
objects have been called.
HttpExceptions
can be thrown to cause a particular HTTP error status code.
req
- The request object.res
- The response object.Exception
- Any exception.@RestHook(value=POST_CALL) public void onPostCall(RestRequest req, RestResponse res) throws Exception
At this point, the output object returned by the method call has been set on the response, but
RestConverters
have not yet been executed and the response has not yet been written.
req
- The request object.res
- The response object.Exception
- Any exception.@RestHook(value=END_CALL) public void onEndCall(HttpServletRequest req, HttpServletResponse res) throws Exception
At this point, the output has been written and flushed.
The following attributes are set on the HttpServletRequest
object that can be useful for logging purposes:
super .parentMethod(...)
.
req
- The HTTP servlet request object.res
- The HTTP servlet response object.Exception
- Any exception.public RestRequest getRequest()
public RestResponse getResponse()
public Swagger getSwagger(RestRequest req) throws Exception
RestInfoProvider
This object is made available through the following:
getSwagger
in interface RestInfoProvider
req
- The incoming HTTP request.Swagger
instance.
Exception
- Throw a HttpException
with a specific HTTP error status or any other exception
to cause a public String getSiteName(RestRequest req) throws Exception
RestInfoProvider
This object is made available through the following:
RestRequest.getSiteName()
getSiteName
in interface RestInfoProvider
req
- The current request.Exception
- Throw a HttpException
with a specific HTTP error status or any other exception
to cause a public String getTitle(RestRequest req) throws Exception
RestInfoProvider
This object is made available through the following:
RestRequest.getResourceTitle()
getTitle
in interface RestInfoProvider
req
- The current request.Exception
- Throw a HttpException
with a specific HTTP error status or any other exception
to cause a public String getDescription(RestRequest req) throws Exception
RestInfoProvider
This object is made available through the following:
RestRequest.getResourceDescription()
getDescription
in interface RestInfoProvider
req
- The current request.Exception
- Throw a HttpException
with a specific HTTP error status or any other exception
to cause a public String getMethodSummary(Method method, RestRequest req) throws Exception
RestInfoProvider
This object is made available through the following:
RestRequest.getMethodSummary()
getMethodSummary
in interface RestInfoProvider
method
- The Java method annotated with @RestMethod
.req
- The current request.Exception
- Throw a HttpException
with a specific HTTP error status or any other exception
to cause a public String getMethodDescription(Method method, RestRequest req) throws Exception
RestInfoProvider
This object is made available through the following:
RestRequest.getMethodDescription()
getMethodDescription
in interface RestInfoProvider
method
- The Java method annotated with @RestMethod
.req
- The current request.Exception
- Throw a HttpException
with a specific HTTP error status or any other exception
to cause a public void log(RestCallLoggerConfig config, HttpServletRequest req, HttpServletResponse res)
RestCallLogger
log
in interface RestCallLogger
config
- The logging configuration.req
- The servlet request.res
- The servlet response.public InputStream findResource(Class<?> baseClass, String name, Locale locale) throws IOException
ResourceFinder
findResource
in interface ResourceFinder
baseClass
- The class to use to retrieve the resource.name
- The resource name.
See Class.getResource(String)
for format.locale
- The locale of the resource to retrieve.
IOException
- Thrown by underlying stream.public <T> T resolve(Object parent, Class<T> c, Object... args)
ResourceResolver
Subclasses can override this method to provide their own custom resolution.
The default implementation simply creates a new class instance using Class.newInstance()
.
resolve
in interface ResourceResolver
parent
- The parent resource.c
- The class to resolve.args
- Optional arguments to pass to constructorpublic <T> T resolve(Object parent, Class<T> c, RestContextBuilder builder, Object... args) throws Exception
RestResourceResolver
Subclasses can override this method to provide their own custom resolution.
The default implementation simply creates a new class instance using Class.newInstance()
.
resolve
in interface RestResourceResolver
parent
- The parent resource (i.e. the instance whose class has the @Rest(children)
annotation.c
- The class to resolve.builder
- The initialization configuration for the resource.args
- Optional arguments to pass to constructorException
- If class could not be resolved.Copyright © 2016–2020 The Apache Software Foundation. All rights reserved.