@Documented @Target(value=METHOD) @Retention(value=RUNTIME) @Inherited @PropertyStoreApply(value=RestMethodConfigApply.class) public @interface RestMethod
RestServlet
implementation class.
Modifier and Type | Optional Element and Description |
---|---|
String[] |
attrs
Default request attributes.
|
Class<?>[] |
beanFilters
Deprecated.
|
String[] |
bpi
Deprecated.
Use
BeanConfig.bpi() |
String[] |
bpx
Deprecated.
Use
BeanConfig.bpx() |
String |
clientVersion
Specifies whether this method can be called based on the client version.
|
String[] |
consumes
Supported content media types.
|
Class<? extends RestConverter>[] |
converters
Class-level response converters.
|
String |
debug
Enable debug mode.
|
String |
defaultAccept
Default
|
String |
defaultCharset
Default character encoding.
|
String |
defaultContentType
Default
|
String[] |
defaultFormData
Specifies default values for form-data parameters.
|
String[] |
defaultQuery
Specifies default values for query parameters.
|
String[] |
defaultRequestHeaders
Default request headers.
|
String[] |
description
Optional description for the exposed API.
|
Class<?>[] |
encoders
Compression encoders.
|
String[] |
flags
Shortcut for setting
properties() of simple boolean types. |
Class<? extends RestGuard>[] |
guards
Method-level guards.
|
HtmlDoc |
htmldoc
Deprecated.
Use
HtmlDocConfig |
Logging |
logging
Specifies rules on how to handle logging of HTTP requests/responses.
|
Class<? extends RestMatcher>[] |
matchers
Method matchers.
|
String |
maxInput
The maximum allowed input size (in bytes) on HTTP requests.
|
String |
method
REST method name.
|
String |
name
REST method name.
|
Class<?>[] |
parsers
Parsers.
|
String |
path
Optional path pattern for the specified method.
|
Class<?>[] |
pojoSwaps
Deprecated.
|
int |
priority
URL path pattern priority.
|
String[] |
produces
Supported accept media types.
|
Property[] |
properties
Same as
@RestResource(properties) , except defines property values by default when this method is called. |
String |
roleGuard
Role guard.
|
String |
rolesDeclared
Declared roles.
|
Class<?>[] |
serializers
Serializers.
|
String |
summary
Optional summary for the exposed API.
|
MethodSwagger |
swagger
Provides swagger-specific metadata on this method.
|
public abstract String[] attrs
Specifies default values for request attributes if they're not already set on the request.
@Deprecated public abstract Class<?>[] beanFilters
BeanConfig.beanFilters()
If no value is specified, the bean filters are inherited from the class.
Otherwise, this value overrides the bean filters defined on the class.
Use Inherit
to inherit bean filters defined on the class.
Use None
to suppress inheriting bean filters defined on the class.
@Deprecated public abstract String[] bpi
BeanConfig.bpi()
BeanContext.BEAN_includeProperties
property on all serializers.
The typical use case is when you're rendering summary and details views of the same bean in a resource and you want to expose or hide specific properties depending on the level of detail you want.
In the example below, our 'summary' view is a list of beans where we only want to show the ID property, and our detail view is a single bean where we want to expose different fields:
@Deprecated public abstract String[] bpx
BeanConfig.bpx()
BeanContext.BEAN_excludeProperties
property on all serializers.
Same as bpi()
except you specify a list of bean property names that you want to exclude from
serialization.
In the example below, our 'summary' view is a list of beans where we want to exclude some properties:
public abstract String clientVersion
The client version is identified via the HTTP request header identified by
@RestResource(clientVersionHeader)
which by default is
This is a specialized kind of RestMatcher
that allows you to invoke different Java methods for the same
method/path based on the client version.
The format of the client version range is similar to that of OSGi versions.
In the following example, the Java methods are mapped to the same HTTP method and URL
It's common to combine the client version with transforms that will convert new POJOs into older POJOs for backwards compatibility.
Note that in the previous example, we're returning the exact same POJO, but using a transform to convert it into an older form. The old method could also just return back a completely different object. The range can be any of the following:
public abstract Class<? extends RestConverter>[] converters
Associates one or more converters
with this method.
public abstract String debug
Enables the following:
public abstract String defaultAccept
The default value for the
This is a shortcut for using defaultRequestHeaders()
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 defaultRequestHeaders()
for just this specific header.
public abstract String[] defaultFormData
Strings are of the format
Affects values returned by RestRequest.getFormData(String)
when the parameter is not present on the
request.
public abstract String[] defaultQuery
Strings are of the format
Affects values returned by RestRequest.getQuery(String)
when the parameter is not present on the request.
public abstract String[] defaultRequestHeaders
Specifies default values for request headers if they're not passed in through the request.
public abstract String[] description
This description is used in the following locations:
RestRequest.getMethodDescription()
.
public abstract Class<?>[] encoders
Use this annotation when the list of encoders assigned to a method differs from the list of encoders assigned at the servlet level.
These can be used to enable various kinds of compression (e.g.
inherit={"ENCODERS" }
to inherit encoders from the resource class.
public abstract String[] flags
properties()
of simple boolean types.
Setting a flag is equivalent to setting the same property to
public abstract Class<? extends RestGuard>[] guards
Associates one or more RestGuards
with this method.
@Deprecated public abstract HtmlDoc htmldoc
HtmlDocConfig
Information provided here overrides information provided in the servlet-level annotation.
public abstract Class<? extends RestMatcher>[] matchers
Associates one more more RestMatchers
with this method.
Matchers are used to allow multiple Java methods to handle requests assigned to the same URL path pattern, but differing based on some request attribute, such as a specific header value.
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 name
Typically
Method names are case-insensitive (always folded to upper-case).
Note that you can use HttpMethodName
for constant values.
Besides the standard HTTP method names, the following can also be specified:
@Method
annotation and/or RestRequest.getMethod()
method can be used to
distinguish the actual HTTP method name.
@RemoteInterface
annotation) to be used as a remote proxy using
public abstract Class<?>[] parsers
If no value is specified, the parsers are inherited from the class.
Otherwise, this value overrides the parsers defined on the class.
Use Inherit
to inherit parsers defined on the class.
Use None
to suppress inheriting parsers defined on the class.
public abstract String path
Appending
Not appending
The path can contain variables that get resolved to @Path
parameters.
If you do not specify a path name, then the path name is inferred from the Java method name.
If you also do not specify the name()
and the Java method name starts with
@Deprecated public abstract Class<?>[] pojoSwaps
BeanConfig.pojoSwaps()
If no value is specified, the POJO swaps are inherited from the class.
Otherwise, this value overrides the POJO swaps defined on the class.
Use Inherit
to inherit POJO swaps defined on the class.
Use None
to suppress inheriting POJO swaps defined on the class.
public abstract int priority
To force path patterns to be checked before other path patterns, use a higher priority number.
By default, it's
public abstract Property[] properties
@RestResource(properties)
, except defines property values by default when this method is called.
This is equivalent to simply calling
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 this method.
rolesDeclared()
or RestContext.REST_rolesDeclared
.
public abstract Class<?>[] serializers
If no value is specified, the serializers are inherited from the class.
Otherwise, this value overrides the serializers defined on the class.
Use Inherit
to inherit serializers defined on the class.
Use None
to suppress inheriting serializers defined on the class.
public abstract String summary
This summary is used in the following locations:
RestRequest.getMethodSummary()
.
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 MethodSwagger swagger
Used to populate the auto-generated OPTIONS swagger documentation.
The format of this annotation is JSON when all individual parts are concatenated.
The starting and ending
Copyright © 2016–2019 The Apache Software Foundation. All rights reserved.