org.apache.juneau.rest.annotation

Annotation Type RestMethod

@Documented
 @Target(value=METHOD)
 @Retention(value=RUNTIME)
 @Inherited
public @interface RestMethod

Identifies a REST Java method on a RestServlet implementation class.

See Also:

• Overview > juneau-rest-server > @RestMethod

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
Class<?>[]	beanFilters Appends the specified bean filters to all serializers and parsers used by 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	defaultCharset Default character encoding.
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<? extends Encoder>[]	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 Identifies what class-level properties are inherited by the serializers and parsers defined on the method.
Class<? extends RestMatcher>[]	matchers Method matchers.
String	maxInput The maximum allowed input size (in bytes) on HTTP requests.
String	name REST method name.
Class<? extends Parser>[]	parsers Parsers.
String	path Optional path pattern for the specified method.
Class<?>[]	pojoSwaps Appends the specified POJO swaps to all serializers and parsers used by 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<? extends Serializer>[]	serializers Serializers.
String	summary Optional summary for the exposed API.
String[]	swagger /** Provides swagger-specific metadata on this method.

Element Detail

beanFilters

public abstract Class<?>[] beanFilters

Appends the specified bean filters to all serializers and parsers used by this method.

See Also:

• BeanContext.BEAN_beanFilters

Default:

{}

bpi

public abstract String[] bpi

Shortcut for specifying the 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:

// Our bean public class MyBean { // Summary properties @Html(link="servlet:/mybeans/{id}") public String id; // Detail properties public String a, b; } // Only render "id" property. @RestMethod(name=GET, path="/mybeans", bpi="MyBean: id") public List<MyBean> getBeanSummary() {...} // Only render "a" and "b" properties. @RestMethod(name=GET, path="/mybeans/{id}", bpi="MyBean: a,b") public MyBean getBeanDetails(@Path String id) {...}

Notes:

• The format of each value is: "Key: comma-delimited-tokens".
• Keys can be fully-qualified or short class names or "*" to represent all classes.
• Values are comma-delimited lists of bean property names.
• Properties apply to specified class and all subclasses.
• Semicolons can be used as an additional separator for multiple values:

  // Equivalent bpi={"Bean1: foo","Bean2: bar,baz"} bpi="Bean1: foo; Bean2: bar,baz"

See Also:

• BeanContext.BEAN_includeProperties

Default:

{}

bpx

public abstract String[] bpx

Shortcut for specifying the 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:

// Our bean public class MyBean { // Summary properties @Html(link="servlet:/mybeans/{id}") public String id; // Detail properties public String a, b; } // Don't show "a" and "b" properties. @RestMethod(name=GET, path="/mybeans", bpx="MyBean: a,b") public List<MyBean> getBeanSummary() {...} // Render all properties. @RestMethod(name=GET, path="/mybeans/{id}") public MyBean getBeanDetails(@Path String id) {...}

Notes:

• The format of each value is: "Key: comma-delimited-tokens".
• Keys can be fully-qualified or short class names or "*" to represent all classes.
• Values are comma-delimited lists of bean property names.
• Properties apply to specified class and all subclasses.
• Semicolons can be used as an additional separator for multiple values:

  // Equivalent bpx={"Bean1: foo","Bean2: bar,baz"} bpx="Bean1: foo; Bean2: bar,baz"

See Also:

• BeanContext.BEAN_excludeProperties

Default:

{}

clientVersion

public abstract String clientVersion

Specifies whether this method can be called based on the client version.

The client version is identified via the HTTP request header identified by @RestResource.clientVersionHeader() which by default is "X-Client-Version".

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 "/foobar".

// Call this method if X-Client-Version is at least 2.0. // Note that this also matches 2.0.1. @RestMethod(name=GET, path="/foobar", clientVersion="2.0") public Object method1() {...} // Call this method if X-Client-Version is at least 1.1, but less than 2.0. @RestMethod(name=GET, path="/foobar", clientVersion="[1.1,2.0)") public Object method2() {...} // Call this method if X-Client-Version is less than 1.1. @RestMethod(name=GET, path="/foobar", clientVersion="[0,1.1)") public Object method3() {...}

It's common to combine the client version with transforms that will convert new POJOs into older POJOs for backwards compatibility.

// Call this method if X-Client-Version is at least 2.0. @RestMethod(name=GET, path="/foobar", clientVersion="2.0") public NewPojo newMethod() {...} // Call this method if X-Client-Version is at least 1.1, but less than 2.0. @RestMethod(name=GET, path="/foobar", clientVersion="[1.1,2.0)", transforms={NewToOldPojoSwap.class}) public NewPojo oldMethod() { return newMethod(); }

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:

• "[0,1.0)" = Less than 1.0. 1.0 and 1.0.0 does not match.
• "[0,1.0]" = Less than or equal to 1.0. Note that 1.0.1 will match.
• "1.0" = At least 1.0. 1.0 and 2.0 will match.

See Also:

• RestContext.REST_clientVersionHeader

Default:

""

converters

public abstract Class<? extends RestConverter>[] converters

Class-level response converters.

Associates one or more converters with this method.

See Also:

• RestContext.REST_converters

Default:

{}

defaultCharset

public abstract String defaultCharset

Default character encoding.

The default character encoding for the request and response if not specified on the request.

Notes:

• Supports initialization-time variables (e.g. "$S{mySystemProperty}").

See Also:

• RestContext.REST_defaultCharset

Default:

""

defaultFormData

public abstract String[] defaultFormData

Specifies default values for form-data parameters.

Strings are of the format "name=value".

Affects values returned by RestRequest.getFormData(String) when the parameter is not present on the request.

Example:

@RestMethod(name=POST, path="/*", defaultFormData={"foo=bar"}) public String doGet(@FormData("foo") String foo) {...}

Notes:

• You can use either ':' or '=' as the key/value delimiter.
• Key and value is trimmed of whitespace.
• Supports initialization-time variables (e.g. "$S{mySystemProperty}").

Default:

{}

defaultQuery

public abstract String[] defaultQuery

Specifies default values for query parameters.

Strings are of the format "name=value".

Affects values returned by RestRequest.getQuery(String) when the parameter is not present on the request.

Example:

@RestMethod(name=GET, path="/*", defaultQuery={"foo=bar"}) public String doGet(@Query("foo") String foo) {...}

Notes:

• You can use either ':' or '=' as the key/value delimiter.
• Key and value is trimmed of whitespace.
• Supports initialization-time variables (e.g. "$S{mySystemProperty}").

Default:

{}

defaultRequestHeaders

public abstract String[] defaultRequestHeaders

Default request headers.

Specifies default values for request headers if they're not passed in through the request.

Example:

// Assume "text/json" Accept value when Accept not specified @RestMethod(name=GET, path="/*", defaultRequestHeaders={"Accept: text/json"}) public String doGet() {...}

Notes:

• Supports initialization-time variables (e.g. "$S{mySystemProperty}").

See Also:

• RestContext.REST_defaultRequestHeaders

Default:

{}

description

public abstract String description

Optional description for the exposed API.

This description is used in the following locations:

• The value returned by RestRequest.getMethodDescription().
• The "$R{methodDescription}" variable.
• The description of the method in the Swagger page.

Notes:

• Corresponds to the swagger field /paths/{path}/{method}/description.
• Supports initialization-time and request-time variables (e.g. "$L{my.localized.variable}").

See Also:

• RestInfoProvider.getDescription(RestRequest)

Default:

""

encoders

public abstract Class<? extends Encoder>[] encoders

Compression 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. "gzip") on requests and responses.

Notes:

• Use inherit={"ENCODERS"} to inherit encoders from the resource class.

See Also:

• RestContext.REST_encoders

Default:

{}

flags

public abstract String[] flags

Shortcut for setting properties() of simple boolean types.

Setting a flag is equivalent to setting the same property to "true".

Default:

{}

guards

public abstract Class<? extends RestGuard>[] guards

Method-level guards.

Associates one or more RestGuards with this method.

See Also:

• RestContext.REST_guards

Default:

{}

htmldoc

public abstract HtmlDoc htmldoc

Provides HTML-doc-specific metadata on this method.

Information provided here overrides information provided in the servlet-level annotation.

See Also:

• Overview > juneau-rest-server > @HtmlDoc

Default:

@org.apache.juneau.rest.annotation.HtmlDoc

inherit

public abstract String inherit

Identifies what class-level properties are inherited by the serializers and parsers defined on the method.

Possible values:

• "SERIALIZERS" - Inherit class-level serializers.
• "PARSERS" - Inherit class-level parsers.
• "TRANSFORMS" - Inherit class-level bean properties and pojo-swaps.
• "PROPERTIES" - Inherit class-level properties (other than transforms).
• "ENCODERS" - Inherit class-level encoders.
• "*" - Inherit everything.

For example, to inherit all parsers, properties, and transforms from the servlet class:

@RestMethod( path="/foo", parsers=MySpecialParser.class, inherit="PARSERS,PROPERTIES,TRANSFORMS" )

Default:

""

matchers

public abstract Class<? extends RestMatcher>[] matchers

Method 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.

See Also:

• RestMatcher

Default:

{}

maxInput

public abstract String maxInput

The maximum allowed input size (in bytes) on HTTP requests.

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.

Example:

@RestMethod( maxInput="100M" )

Notes:

• Supports initialization-time variables (e.g. "$S{mySystemProperty}").

See Also:

• RestContext.REST_maxInput

Default:

""

name

public abstract String name

REST method name.

Typically "GET", "PUT", "POST", "DELETE", or "OPTIONS".

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:

• "*" - Denotes any method.
  Use this if you want to capture any HTTP methods in a single Java method.
  The @Method annotation and/or RestRequest.getMethod() method can be used to distinguish the actual HTTP method name.
• "" - Auto-detect.
  The method name is determined based on the Java method name.
  For example, if the method is doPost(...), then the method name is automatically detected as "POST".
  Otherwise, defaults to "GET".
• "PROXY" - Remote-proxy interface.
  This denotes a Java method that returns an object (usually an interface, often annotated with the @Remoteable annotation) to be used as a remote proxy using RestClient.getRemoteableProxy(Class<T> interfaceClass, String url).
  This allows you to construct client-side interface proxies using REST as a transport medium.
  Conceptually, this is simply a fancy POST against the url "/{path}/{javaMethodName}" where the arguments are marshalled from the client to the server as an HTTP body containing an array of objects, passed to the method as arguments, and then the resulting object is marshalled back to the client.
• Anything else - Overloaded non-HTTP-standard names that are passed in through a &method=methodName URL parameter.

Default:

""

parsers

public abstract Class<? extends Parser>[] parsers

Parsers.

Overrides the list of parsers assigned at the method level.

Use this annotation when the list of parsers assigned to a method differs from the list of parsers assigned at the servlet level.

To append to the list of parsers assigned at the servlet level, use inherit="PARSERS".

public class MyResource extends RestServlet { @RestMethod( name=PUT, path="/foo", parsers=MySpecialParser.class, inherit="PARSERS" ) public Object doGetWithSpecialAcceptType() { // Handle request for special Accept type } }

See Also:

• RestContext.REST_parsers

Default:

{}

path

public abstract String path

Optional path pattern for the specified method.

Appending "/*" to the end of the path pattern will make it match any remainder too.
Not appending "/*" to the end of the pattern will cause a 404 (Not found) error to occur if the exact pattern is not found.

The path can contain variables that get resolved to @Path parameters:

// Example 1 @RestMethod(name=GET, path="/myurl/{foo}/{bar}/{baz}/*") // Example 2 @RestMethod(name=GET, path="/myurl/{0}/{1}/{2}/*")

See Also:

• Path

Default:

"/*"

pojoSwaps

public abstract Class<?>[] pojoSwaps

Appends the specified POJO swaps to all serializers and parsers used by this method.

See Also:

• BeanContext.BEAN_pojoSwaps

Default:

{}

priority

public abstract int priority

URL path pattern 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.

Default:

0

properties

public abstract Property[] properties

Same as @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.

Default:

{}

serializers

public abstract Class<? extends Serializer>[] serializers

Serializers.

Overrides the list of serializers assigned at the method level.

Use this annotation when the list of serializers assigned to a method differs from the list of serializers assigned at the servlet level.

To append to the list of serializers assigned at the servlet level, use inherit="SERIALIZERS".

Example:

public class MyResource extends RestServlet { @RestMethod( name=GET, path="/foo", serializers=MySpecialSerializer.class, inherit="SERIALIZERS" ) public Object doGetWithSpecialAcceptType() { // Handle request for special Accept type } }

See Also:

• RestContext.REST_serializers

Default:

{}

summary

public abstract String summary

Optional summary for the exposed API.

This summary is used in the following locations:

• The value returned by RestRequest.getMethodSummary().
• The "$R{methodSummary}" variable.
• The summary of the method in the Swagger page.

Notes:

• Corresponds to the swagger field /paths/{path}/{method}/summary.
• Supports initialization-time and request-time variables (e.g. "$L{my.localized.variable}").

Default:

""

produces

public abstract String[] produces

Supported accept media types.

Overrides the media types inferred from the serializers that identify what media types can be produced by the resource.

Notes:

• Supports initialization-time variables (e.g. "$S{mySystemProperty}").

See Also:

• RestContext.REST_produces

Default:

{}

consumes

public abstract String[] consumes

Supported content media types.

Overrides the media types inferred from the parsers that identify what media types can be consumed by the resource.

Notes:

• Supports initialization-time variables (e.g. "$S{mySystemProperty}").

See Also:

• RestContext.REST_consumes

Default:

{}

swagger

public abstract String[] swagger

/** Provides swagger-specific metadata on this method.

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 '{'/'}' characters around the entire value are optional.

Example:

@RestMethod( name=PUT, path="/{propertyName}", // Swagger info. swagger={ "parameters:[", "{name:'propertyName',in:'path',description:'The system property name.'},", "{in:'body',description:'The new system property value.'}", "],", "responses:{", "302: {headers:{Location:{description:'The root URL of this resource.'}}},", "403: {description:'User is not an admin.'}", "}" } )

See Also:

• RestInfoProvider.getSwagger(RestRequest)

Default:

{}