@Documented @Target(value=METHOD) @Retention(value=RUNTIME) @Inherited public @interface RestMethod
RestServlet
implementation class.
Modifier and Type | Optional Element and Description |
---|---|
Class<?>[] |
beanFilters
Sets the bean filters for the serializers and parsers defined on this method.
|
String[] |
bpi
Shortcut for specifying the
BeanContext.BEAN_includeProperties property on all serializers. |
String[] |
bpx
Shortcut for specifying the
BeanContext.BEAN_excludeProperties property on all serializers. |
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 |
defaultAccept
Default
Accept header. |
String |
defaultCharset
Default character encoding.
|
String |
defaultContentType
Default
Content-Type header. |
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
Provides HTML-doc-specific metadata on this method.
|
String |
inherit
Deprecated.
Use
Inherit on annotations. |
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
Sets the POJO swaps for the serializers and parsers defined on this method.
|
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. |
Class<?>[] |
serializers
Serializers.
|
String |
summary
Optional summary for the exposed API.
|
MethodSwagger |
swagger
Provides swagger-specific metadata on this method.
|
public abstract Class<?>[] 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.
public abstract String[] 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:
public abstract String[] 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 defaultAccept
Accept
header.
The default value for the Accept
header if not specified on a request.
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
Content-Type
header.
The default value for the Content-Type
header if not specified on a request.
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()
.
/paths/{path}/{method}/description
.
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.
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.
doPost(...)
, then the method name is automatically detected
as @RemoteInterface
annotation) to be used as a remote proxy using
RestClient.getRemoteInterface(Class<T> interfaceClass, String url)
.
POST
against the url &method=methodName
URL
parameter.
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
public abstract Class<?>[] 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 0
, which means it will use an internal heuristic to determine a best match.
public abstract Property[] properties
@RestResource(properties)
, except defines property values by default when this method is called.
This is equivalent to simply calling res.addProperties()
in the Java method, but is provided for
convenience.
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()
.
/paths/{path}/{method}/summary
.
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
@Deprecated public abstract String inherit
Inherit
on annotations.Copyright © 2018 Apache. All rights reserved.