@Documented @Target(value=TYPE) @Retention(value=RUNTIME) @Inherited @PropertyStoreApply(value=RestConfigApply.class) public @interface Rest
Usually used on a subclass of RestServlet
, but can be used to annotate any class that you want to expose as
a REST resource.
Modifier and Type | Optional Element and Description |
---|---|
String |
allowBodyParam
Allow body URL parameter.
|
String |
allowedHeaderParams
Configuration property: Allowed header URL parameters.
|
String |
allowedMethodHeaders
Configuration property: Allowed method headers.
|
String |
allowedMethodParams
Allowed method parameters.
|
String[] |
attrs
Deprecated.
|
Class<? extends RestCallHandler> |
callHandler
Deprecated.
|
Class<? extends RestCallLogger> |
callLogger
Specifies the logger to use for logging of HTTP requests and responses.
|
Class<?>[] |
children
REST children.
|
Class<? extends ResourceFinder> |
classpathResourceFinder
Classpath resource finder.
|
String |
clientVersionHeader
Client version header.
|
String |
config
Optional location of configuration file for this servlet.
|
String[] |
consumes
Supported content media types.
|
Class<? extends RestContext> |
context
Allows you to extend the
RestContext class to modify how any of the methods are implemented. |
Class<? extends RestConverter>[] |
converters
Class-level response converters.
|
String |
debug
Enable debug mode.
|
String |
debugOn
Enable debug mode on specified classes/methods.
|
String |
defaultAccept
Default
|
String |
defaultCharset
Default character encoding.
|
String |
defaultContentType
Default
|
String[] |
defaultRequestHeaders
Deprecated.
|
String[] |
defaultResponseHeaders
Deprecated.
|
String[] |
description
Optional servlet description.
|
Class<? extends Encoder>[] |
encoders
Compression encoders.
|
String[] |
flags
Shortcut for setting
properties() of simple boolean types. |
Class<? extends RestGuard>[] |
guards
Class-level guards.
|
Class<? extends RestInfoProvider> |
infoProvider
Configuration property: REST info provider.
|
Logging |
logging
Specifies rules on how to handle logging of HTTP requests/responses.
|
String |
maxInput
The maximum allowed input size (in bytes) on HTTP requests.
|
String |
messages
Messages.
|
String[] |
mimeTypes
Configuration property: MIME types.
|
Class<? extends RestMethodParam>[] |
paramResolvers
Java method parameter resolvers.
|
Class<?>[] |
parsers
Parsers.
|
Class<? extends HttpPartParser> |
partParser
HTTP part parser.
|
Class<? extends HttpPartSerializer> |
partSerializer
HTTP part serializer.
|
String |
path
Resource path.
|
String[] |
produces
Supported accept media types.
|
Property[] |
properties
Class-level properties.
|
String |
renderResponseStackTraces
Render response stack traces in responses.
|
String[] |
reqAttrs
Default request attributes.
|
String[] |
reqHeaders
Default request headers.
|
String[] |
resHeaders
Default response headers.
|
Class<? extends RestResourceResolver> |
resourceResolver
REST resource resolver.
|
Class<? extends ResponseHandler>[] |
responseHandlers
Response handlers.
|
String |
roleGuard
Role guard.
|
String |
rolesDeclared
Declared roles.
|
Class<?>[] |
serializers
Serializers.
|
String |
siteName
Optional site name.
|
String[] |
staticFileResponseHeaders
Static file response headers.
|
String[] |
staticFiles
Static file mappings.
|
ResourceSwagger |
swagger
Provides swagger-specific metadata on this resource.
|
String[] |
title
Optional servlet title.
|
String |
uriAuthority
Resource authority path.
|
String |
uriContext
Resource context path.
|
String |
uriRelativity
URI-resolution relativity.
|
String |
uriResolution
URI-resolution.
|
String |
useClasspathResourceCaching
Configuration property: Use classpath resource caching.
|
public abstract String allowBodyParam
When enabled, the HTTP body content on PUT and POST requests can be passed in as text using the
For example:
?body=(name='John%20Smith',age=45)
public abstract String allowedHeaderParams
When specified, allows headers such as
For example:
?Accept=text/json&Content-Type=text/json
public abstract String allowedMethodHeaders
A comma-delimited list of HTTP method names that are allowed to be passed as values in an
Allows you to override the actual HTTP method with a simulated method.
For example, if an HTTP Client API doesn't support
public abstract String allowedMethodParams
When specified, the HTTP method can be overridden by passing in a
For example:
?method=OPTIONS
@Deprecated public abstract String[] attrs
reqAttrs()
@Deprecated public abstract Class<? extends RestCallHandler> callHandler
RestContext.REST_context
and override methods.
public abstract Class<? extends ResourceFinder> classpathResourceFinder
Used to retrieve localized files from the classpath.
BasicResourceFinder
.
ResourceFinder
interface and not
explicitly overridden via this annotation.
RestServlet
and BasicRest
classes implement the ResourceFinder
interface with the same
functionality as BasicResourceFinder
that gets used if not overridden by this annotation.
public T(RestContext)
public T()
public static T create (RestContext)
public static T create ()
public abstract String clientVersionHeader
Specifies the name of the header used to denote the client version on HTTP requests.
public abstract String config
The configuration file .
Config.getSystemDefault()
.
public abstract Class<? extends RestContext> context
RestContext
class to modify how any of the methods are implemented.
The subclass must provide the following:
RestContextBuilder
.
public abstract Class<? extends RestConverter>[] converters
Associates one or more converters
with a resource class.
public abstract String debug
Enables the following:
RestCallLogger
.
Possible values (case insensitive):
debugOn()
annotation or at runtime by directly
calling RestRequest.setDebug()
.
public abstract String debugOn
Enables the following:
RestCallLogger
.
Consists of a comma-delimited list of strings of the following forms:
Class identifiers can be any of the following forms:
Method identifiers can be any of the following forms:
A more-typical scenario is to pull this setting from an external source such as system property or environment variable:
debug()
and RestMethod.debug()
.
RestRequest.setDebug()
.
public abstract String defaultAccept
The default value for the
This is a shortcut for using reqHeaders()
for just this specific header.
public abstract String defaultCharset
The default character encoding for the request and response if not specified on the request.
public abstract String defaultContentType
The default value for the
This is a shortcut for using reqHeaders()
for just this specific header.
@Deprecated public abstract String[] defaultRequestHeaders
reqHeaders()
@Deprecated public abstract String[] defaultResponseHeaders
resHeaders()
public abstract String[] description
It is used to populate the Swagger description field.
This value can be retrieved programmatically through the RestRequest.getResourceDescription()
method.
public abstract String[] flags
properties()
of simple boolean types.
public abstract Class<? extends RestGuard>[] guards
Associates one or more RestGuards
with all REST methods defined in this class.
public abstract Class<? extends RestInfoProvider> infoProvider
Class used to retrieve title/description/swagger information about a resource.
BasicRestInfoProvider
.
RestInfoProvider
interface and not
explicitly overridden via this annotation.
RestServlet
and BasicRest
classes implement the RestInfoProvider
interface with the same
functionality as BasicRestInfoProvider
that gets used if not overridden by this annotation.
public T(RestContext)
public T()
public static T create (RestContext)
public static T create ()
public abstract Class<? extends RestCallLogger> callLogger
BasicRestCallLogger
.
RestCallLogger
interface and not
explicitly overridden via this annotation.
RestServlet
and BasicRest
classes implement the RestCallLogger
interface with the same
functionality as BasicRestCallLogger
that gets used if not overridden by this annotation.
public T(RestContext)
public T()
public static T create (RestContext)
public static T create ()
public abstract String maxInput
Useful for alleviating DoS attacks by throwing an exception when too much input is received instead of resulting in out-of-memory errors which could affect system stability.
public abstract String messages
public abstract String[] mimeTypes
Defines MIME-type file type mappings.
public abstract Class<? extends RestMethodParam>[] paramResolvers
By default, the Juneau framework will automatically Java method parameters of various types (e.g.
This setting allows you to provide your own resolvers for your own class types that you want resolved.
public abstract Class<?>[] parsers
If no value is specified, the parsers are inherited from parent class.
Otherwise, this value overrides the parsers defined on the parent class.
Use Inherit
to inherit parsers defined on the parent class.
Use None
to suppress inheriting parsers defined on the parent class.
public abstract Class<? extends HttpPartParser> partParser
Specifies the HttpPartParser
to use for parsing headers, query/form parameters, and URI parts.
public abstract Class<? extends HttpPartSerializer> partSerializer
Specifies the HttpPartSerializer
to use for serializing headers, query/form parameters, and URI parts.
public abstract String path
Used in the following situations:
children()
annotation) to identify
the subpath used to access the child resource relative to the parent.
RestServlet
classes deployed as Spring beans when The typical usage is to define a path to a child resource relative to the parent resource.
In the example above, assuming the
Note that in this scenario, the
The path can also be used on top-level resources deployed as Spring beans when used with the
In this case, the servlet will get registered using the path defined on the resource class.
The path can contain variables that get resolved to @Path
parameters
or access through the RestRequest.getPathMatch()
method.
Variables can be used on either top-level or child resources and can be defined on multiple levels.
All variables in the path must be specified or else the target will not resolve and a
When variables are used on a path of a top-level resource deployed as a Spring bean in a Spring Boot application, the first part of the URL must be a literal which will be used as the servlet path of the registered servlet.
public abstract Property[] properties
Shortcut to add properties to the bean contexts of all serializers and parsers on all methods in the class.
Any of the properties defined on RestContext
or any of the serializers and parsers can be specified.
Property values will be converted to the appropriate type.
public abstract String renderResponseStackTraces
Render stack traces in HTTP response bodies when errors occur.
public abstract String[] reqAttrs
Specifies default values for request attributes if they're not already set on the request.
public abstract String[] reqHeaders
Specifies default values for request headers if they're not passed in through the request.
public abstract String[] resHeaders
Specifies default values for response headers if they're not set after the Java REST method is called.
public abstract Class<? extends RestResourceResolver> resourceResolver
The resolver used for resolving child resources.
RestResourceResolver
interface and not
explicitly overridden via this annotation.
RestServlet
and BasicRest
classes implement the RestResourceResolver
interface with the same
functionality as BasicRestResourceResolver
that gets used if not overridden by this annotation.
public T(RestContext)
public T()
public static T create (RestContext)
public static T create ()
public abstract Class<? extends ResponseHandler>[] responseHandlers
Specifies a list of ResponseHandler
classes that know how to convert POJOs returned by REST methods or
set via RestResponse.setOutput(Object)
into appropriate HTTP responses.
public abstract String rolesDeclared
A comma-delimited list of all possible user roles.
Used in conjunction with roleGuard()
is used with patterns.
public abstract String roleGuard
An expression defining if a user with the specified roles are allowed to access methods on this class.
rolesDeclared()
or RestContext.REST_rolesDeclared
.
public abstract Class<?>[] serializers
If no value is specified, the serializers are inherited from parent class.
Otherwise, this value overrides the serializers defined on the parent class.
Use Inherit
to inherit serializers defined on the parent class.
Use None
to suppress inheriting serializers defined on the parent class.
public abstract String siteName
The site name is intended to be a title that can be applied to the entire site.
This value can be retrieved programmatically through the RestRequest.getSiteName()
method.
One possible use is if you want to add the same title to the top of all pages by defining a header on a common parent class like so:
public abstract String[] staticFileResponseHeaders
Used to customize the headers on responses returned for statically-served files.
Note that headers can also be specified per path-mapping via the Rest(staticFiles)
annotation.
public abstract String[] staticFiles
Used to define paths and locations of statically-served files such as images or HTML documents from the classpath or file system.
The format of the value is one of the following:
An example where this class is used is in the staticFiles()
annotation:
In the example above, given a GET request to the following URL...
/myresource/htdocs/foobar.html
The location is interpreted as an absolute path if it starts with
In the example above, given a GET request to the following URL...
/myresource/htdocs/foobar.html
Response headers can be specified for served files by adding a 3rd section that consists of a Overview > juneau-marshall > JSON Details > Simplified JSON object.
The same path can map to multiple locations. Files are searched in the order
public abstract String[] produces
Overrides the media types inferred from the serializers that identify what media types can be produced by the resource.
public abstract String[] consumes
Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource.
public abstract ResourceSwagger swagger
Used to populate the auto-generated OPTIONS swagger documentation.
public abstract String[] title
It is used to populate the Swagger title field.
This value can be retrieved programmatically through the RestRequest.getResourceTitle()
method.
public abstract String uriAuthority
Overrides the authority path value for this resource and any child resources.
public abstract String uriContext
Overrides the context path value for this resource and any child resources.
public abstract String uriRelativity
Specifies how relative URIs should be interpreted by serializers.
See UriResolution
for possible values.
public abstract String uriResolution
Specifies how relative URIs should be interpreted by serializers.
See UriResolution
for possible values.
public abstract String useClasspathResourceCaching
When enabled, resources retrieved via RestRequest.getClasspathHttpResource(String, boolean)
(and related
methods) will be cached in memory to speed subsequent lookups.
Copyright © 2016–2020 The Apache Software Foundation. All rights reserved.