Package org.apache.juneau.rest.server

Annotation Interface RestOp

@Target(METHOD)
@Retention(RUNTIME)
@Inherited
@AnnotationGroup(RestOp.class)
public @interface RestOp

Identifies a REST operation Java method on a RestServlet implementation class.

See Also:

• @RestOp-Annotated Method

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String[]	allowedParserOptions	Allowed parser session option keys for this operation (ordered merge, prefix -key removes a key).
String[]	allowedSerializerOptions	Allowed serializer session option keys for this operation (ordered merge, prefix -key removes a key).
String	asyncCompletionExecutor	Per-operation override for @Rest(asyncCompletionExecutor).
String	asyncTimeoutMillis	Per-operation override for @Rest(asyncTimeoutMillis).
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	debugMarshalling	Per-operation override for @Rest(debugMarshalling).
String	defaultAccept	Default Accept header.
String	defaultCharset	Default character encoding.
String	defaultContentType	Default Content-Type header.
String[]	defaultRequestAttributes	Default request attributes.
String[]	defaultRequestFormData	Specifies default values for form-data parameters.
String[]	defaultRequestHeaders	Default request headers.
String[]	defaultRequestQueryData	Specifies default values for query parameters.
String[]	defaultResponseHeaders	Default response headers.
String[]	description	Optional description for the exposed API.
Class<? extends Encoder>[]	encoders	Specifies the compression encoders for this method.
Class<? extends RestGuard>[]	guards	Method-level guards.
Class<? extends RestMatcher>[]	matchers	Method matchers.
String	maxInput	The maximum allowed input size (in bytes) on HTTP requests.
String	method	REST method name.
String	metricName	Per-operation metric name override.
String	metricTags	Per-operation metric tags.
String[]	noInherit	Property names for which less-derived contributions are NOT inherited.
String	observability	Per-operation observability opt-in / opt-out control.
Class<?>[]	parsers	Specifies the parsers for converting HTTP request bodies into POJOs for this method.
String[]	path	Optional path pattern for the specified method.
String	problemDetails	Per-operation override for @Rest(problemDetails).
String[]	produces	Supported accept media types.
boolean	read	Declares that this operation's custom method is a read.
String	roleGuard	Role guard.
String	rolesDeclared	Declared roles.
Class<? extends Serializer>[]	serializers	Specifies the serializers for marshalling POJOs into response bodies for this method.
String	summary	Optional summary for the exposed API.
OpSwagger	swagger	Provides swagger-specific metadata on this method.
String	value	REST method name and path.
String	virtualThreads	Per-operation override for @Rest(virtualThreads).

Element Details

clientVersion

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 @Rest(clientVersionHeader) which by default is "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 Client-Version is at least 2.0. // Note that this also matches 2.0.1. @RestOp(method=GET, path="/foobar", clientVersion="2.0") public Object method1() {...} // Call this method if Client-Version is at least 1.1, but less than 2.0. @RestOp(method=GET, path="/foobar", clientVersion="[1.1,2.0)") public Object method2() {...} // Call this method if Client-Version is less than 1.1. @RestOp(method=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 Client-Version is at least 2.0. @RestOp(method=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. @RestOp(method=GET, path="/foobar", clientVersion="[1.1,2.0)") @MarshalledConfig(swaps=NewToOldSwap.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:

• Rest.clientVersionHeader()

Returns:

The annotation value.

Default:

""

consumes

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 REST Server SVL Variables (e.g. "$S{mySystemProperty}").

See Also:

• RestOpContext.getSupportedContentTypes()

Returns:

The annotation value.

Default:

{}

converters

Class<? extends RestConverter>[] converters

Class-level response converters.

Associates one or more converters with this method.

Returns:

The annotation value.

Default:

{}

defaultAccept

String defaultAccept

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

Returns:

The annotation value.

Default:

""

defaultCharset

String defaultCharset

Default character encoding.

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

Notes:

• Supports REST Server SVL Variables (e.g. "$S{mySystemProperty}").

See Also:

• Rest.defaultCharset()

Returns:

The annotation value.

Default:

""

defaultContentType

String defaultContentType

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

Returns:

The annotation value.

Default:

""

defaultRequestAttributes

String[] defaultRequestAttributes

Default request attributes.

Specifies default values for request attributes if they're not already set on the request.

Affects values returned by the following methods:

• RestRequest.getAttribute(String).
• RestRequest.getAttributes().

Example:

// Defined via annotation resolving to a config file setting with default value. @Rest(defaultRequestAttributes={"Foo=bar", "Baz: $C{REST/myAttributeValue}"}) public class MyResource { // Override at the method level. @RestGet(defaultRequestAttributes={"Foo: bar"}) public Object myMethod() {...} }

Notes:

• Supports REST Server SVL Variables (e.g. "$L{my.localized.variable}").

See Also:

• Rest.defaultRequestAttributes()