Annotation Interface RestOp


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

See Also:

  • Element Details

    • 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:

      Returns:
      The annotation value.
      Default:
      ""
    • 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:

      See Also:

      Returns:
      The annotation value.
      Default:
      {}
    • converters

      Class-level response converters.

      Associates one or more converters with this method.

      Returns:
      The annotation value.
      Default:
      {}
    • 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

      Default character encoding.

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

      Notes:

      See Also:

      Returns:
      The annotation value.
      Default:
      ""
    • 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

      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:

      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:

      See Also:

      Returns:
      The annotation value.
      Default:
      {}
    • defaultRequestFormData

      Specifies default values for form-data parameters.

      Strings are of the format "name=value".

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

      Example:

      @RestOp(method=POST, path="/*", defaultRequestFormData={"foo=bar"}) public String doPost(@FormData("foo") String foo) {...}

      Notes:

      • You can use either ':' or '=' as the key/value delimiter.
      • Key and value is trimmed of whitespace.
      • Supports REST Server SVL Variables (e.g. "${S:mySystemProperty}").
      Returns:
      The annotation value.
      Default:
      {}
    • 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 @RestOp(method=GET, path="/*", defaultRequestHeaders={"Accept: text/json"}) public String doGet() {...}

      Notes:

      Returns:
      The annotation value.
      Default:
      {}
    • defaultRequestQueryData

      Specifies default values for query parameters.

      Strings are of the format "name=value".

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

      Example:

      @RestOp(method=GET, path="/*", defaultRequestQueryData={"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 REST Server SVL Variables (e.g. "${S:mySystemProperty}").
      Returns:
      The annotation value.
      Default:
      {}
    • defaultResponseHeaders

      Default response headers.

      Specifies default values for response headers if they're not overwritten during the request.

      Example:

      // Assume "text/json" Accept value when Accept not specified @RestOp(method=GET, path="/*", defaultResponseHeaders={"Content-Type: text/json"}) public String doGet() {...}

      Notes:

      Returns:
      The annotation value.
      Default:
      {}
    • description

      Optional description for the exposed API.

      This description is used in the following locations:

      • The value returned by Operation.getDescription() in the auto-generated swagger.
      • The "${RS:operationDescription}" variable.
      • The description of the method in the Swagger page.

      Notes:

      • Corresponds to the swagger field /paths/{path}/{method}/description.
      • Supports REST Server SVL Variables (e.g. "${L:my.localized.variable}").
      Returns:
      The annotation value.
      Default:
      {}
    • encoders

      Class<? extends Encoder>[] encoders
      Specifies the compression encoders for this method.

      Encoders are used to enable various kinds of compression (e.g. "gzip") on requests and responses.

      This value overrides encoders specified at the class level using Rest.encoders(). The EncoderSet.Inherit class can be used to include values from the parent class.

      Example:

      // Define a REST resource that handles GZIP compression. @Rest( encoders={ GzipEncoder.class } ) public class MyResource { // Define a REST method that can also use a custom encoder. @RestOp( method=GET, encoders={ EncoderSet.Inherit.class, MyEncoder.class } ) public MyBean doGet() { ... } }

      For programmatic equivalents, contribute a EncoderSet bean via @Bean(name="encoders") (use methodScope to scope to specific operation methods).

      See Also:

      Returns:
      The annotation value.
      Default:
      {}
    • guards

      Class<? extends RestGuard>[] guards
      Method-level guards.

      Associates one or more RestGuards with this method.

      Returns:
      The annotation value.
      Default:
      {}
    • matchers

      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:

      Returns:
      The annotation value.
      Default:
      {}
    • 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:

      @RestOp( maxInput="10M" )

      Notes:

      See Also:

      Returns:
      The annotation value.
      Default:
      ""
    • method

      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 HttpMethod for constant values.

      Note that you can also use value() to specify the method name and path in shortened form.

      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".
      • "RRPC" - Remote-proxy interface.
        This denotes a Java method that returns an object (usually an interface, often annotated with the @Remote annotation) to be used as a remote proxy using RestClient.getRemoteInterface(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 content 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.
        On a safe request (GET, HEAD, OPTIONS, TRACE), only when the operation is declared read=true.
      Returns:
      The annotation value.
      Default:
      ""
    • parsers

      Specifies the parsers for converting HTTP request bodies into POJOs for this method.

      Parsers are used to convert the content of HTTP requests into POJOs.
      Any of the Juneau framework parsers can be used in this setting.
      The parser selected is based on the request Content-Type header matched against the values returned by the following method using a best-match algorithm:

      This value overrides parsers specified at the class level using Rest.parsers(). The ParserSet.Inherit class can be used to include values from the parent class.

      Example:

      // Define a REST resource that can consume JSON and HTML. @Rest( parsers={ JsonParser.class, HtmlParser.class } ) public class MyResource { // Define a REST method that can also consume XML. @RestOp( method=POST, parsers={ ParserSet.Inherit.class, XmlParser.class } ) public void doPost(MyBean bean) { ... } }

      For programmatic equivalents, contribute a ParserSet bean via @Bean(name="parsers") (use methodScope to scope to specific operation methods).

      See Also:

      Returns:
      The annotation value.
      Default:
      {}
    • 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.

      Examples:

      @RestOp(method=GET, path="/myurl/{foo}/{bar}/{baz}/*")

      @RestOp(method=GET, path="/myurl/{0}/{1}/{2}/*")

      If you do not specify a path name, then the path name is inferred from the Java method name.

      Example:

      // Path is assumed to be "/foo". @RestOp(method=GET) public void foo() {...}

      If you also do not specify the method() and the Java method name starts with "get", "put", "post", or "delete", then the HTTP method name is stripped from the inferred path.

      Examples:

      // Method is GET, path is "/foo". @RestOp public void getFoo() {...}

      // Method is DELETE, path is "/bar". @RestOp public void deleteBar() {...}

      // Method is GET, path is "/foobar". @RestOp public void foobar() {...}

      // Method is GET, path is "/". @RestOp public void get() {...}

      Note that you can also use value() to specify the method name and path in shortened form.

      See Also:

      Returns:
      The annotation value.
      Default:
      {}
    • problemDetails

      Per-operation override for @Rest(problemDetails).

      When set on a @RestOp method, this value takes precedence over the resource-level @Rest(problemDetails) attribute for this operation. Tri-state semantics:

      • "true" — enable problem-details responses for this operation.
      • "false" — disable problem-details responses for this operation (overrides an opted-in resource).
      • "" (default) — inherit from Rest.problemDetails().

      Notes:

      See Also:

      Returns:
      The annotation value.
      Default:
      ""
    • debugMarshalling

      Per-operation override for @Rest(debugMarshalling).

      When set on a @RestOp method, this value takes precedence over the resource-level @Rest(debugMarshalling) attribute for this operation. Tri-state semantics:

      • "true" — enable marshalling debug for this operation.
      • "false" — disable marshalling debug for this operation (overrides an opted-in resource).
      • "" (default) — inherit from Rest.debugMarshalling().

      Notes:

      See Also:

      Returns:
      The annotation value.
      Default:
      ""
    • virtualThreads

      Per-operation override for @Rest(virtualThreads).

      When set, this value takes precedence over the resource-level setting for this operation. Tri-state semantics:

      • "true" — enable virtual-thread dispatch for this operation (Java 21+ only; gracefully ignored on older JVMs).
      • "false" — disable virtual-thread dispatch for this operation (overrides an opted-in resource).
      • "" (default) — inherit from Rest.virtualThreads().

      Notes:

      See Also:

      Returns:
      The annotation value.
      Default:
      ""
    • observability

      Per-operation observability opt-in / opt-out control.

      Overrides the resource-level Rest.observability() setting for this specific operation. Controls whether the observability block (MetricsRecorder / TracerHook) fires for this operation.

      • "true" — strict opt-in: this operation requires a wired observability backend. If neither a @Bean MetricsRecorder nor a @Bean TracerHook is registered when the RestContext is built, construction fails with a precise error.
      • "false" — explicit opt-out: the observability block is short-circuited for this operation, even when a wired backend is present. Also suppresses TraceContextResponseProcessor header injection.
      • "" (default) — inherits the resource-level Rest.observability() setting. If the resource-level setting is also empty, uses the existing behavior: the observability block runs per-op, but a missing backend silently falls back to the NoOp singleton.

      Notes:

      See Also:

      Returns:
      The annotation value.
      Since:
      10.0.0
      Default:
      ""
    • metricName

      Per-operation metric name override.

      Overrides the metric name passed to record() for this operation. When empty (default), the recorder uses its own default name derivation (typically the fully-qualified operation name).

      Notes:

      Returns:
      The annotation value.
      Since:
      10.0.0
      Default:
      ""
    • metricTags

      Per-operation metric tags.

      Additional metric tags to pass to record(). Format: comma-separated key=value pairs, e.g. "team=payments,region=us-east". When empty (default), no additional tags are passed.

      Notes:

      • Supports REST Server SVL Variables.
      • The recorder implementation is responsible for parsing the comma-separated key=value string.
      • Has no effect when observability is disabled for this operation.
      Returns:
      The annotation value.
      Since:
      10.0.0
      Default:
      ""
    • asyncTimeoutMillis

      Per-operation override for @Rest(asyncTimeoutMillis).

      Configurable timeout (milliseconds) applied to CompletableFuture-returning handlers. Default is 30,000 ms inherited from the resource. Set to "0" to disable the timeout.

      Notes:

      See Also:

      Returns:
      The annotation value.
      Default:
      ""
    • asyncCompletionExecutor

      Per-operation override for @Rest(asyncCompletionExecutor).

      Names the Executor bean used to route completion callbacks for this specific operation through a dedicated thread pool. Empty string (default) inherits from Rest.asyncCompletionExecutor().

      See Also:

      Returns:
      The annotation value.
      Since:
      10.0.0
      Default:
      ""
    • 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:

      See Also:

      Returns:
      The annotation value.
      Default:
      {}
    • allowedSerializerOptions

      Allowed serializer session option keys for this operation (ordered merge, prefix -key removes a key).

      Comma-delimited list of session property keys that clients may send via the "X-Juneau-Serializer-Options" header or "juneauSerializerOptions" query parameter. Merged on top of resource-level Rest.allowedSerializerOptions() values. Use noInherit() to replace rather than extend the resource-level list.

      See Also:

      Returns:
      The annotation value.
      Default:
      {}
    • allowedParserOptions

      Allowed parser session option keys for this operation (ordered merge, prefix -key removes a key).

      Comma-delimited list of session property keys that clients may send via the "X-Juneau-Parser-Options" header or "juneauParserOptions" query parameter. Merged on top of resource-level Rest.allowedParserOptions() values. Use noInherit() to replace rather than extend the resource-level list.

      See Also:

      Returns:
      The annotation value.
      Default:
      {}
    • noInherit

      Property names for which less-derived contributions are NOT inherited.

      Accepted values: "allowedSerializerOptions", "allowedParserOptions", "problemDetails", "debugMarshalling". Prevents the named property from inheriting values from the enclosing @Rest annotation. The noInherit attribute itself is never inherited.

      See Also:

      Returns:
      The annotation value.
      Default:
      {}
    • read

      boolean read
      Declares that this operation's custom method is a read.

      A request whose request line is safe (GET, HEAD, OPTIONS or TRACE) may be overridden (through the method query parameter or an override header, see Rest.allowedMethodParams() and Rest.allowedMethodHeaders()) only to another safe method, or to the method of an operation declared read=true. Any other override of a safe request is refused with 405 Method Not Allowed, so a link, a crawler or a prefetcher following a plain GET can never reach an operation that changes state.

      Example:

      // Reachable as GET /files/foo.txt?method=VIEW, as well as VIEW /files/foo.txt. @RestOp(method="VIEW", path="/files/*", read=true) public Reader view(...) {...}

      The declaration is the developer's promise that the operation does not change state, exactly as GET promises. Nothing can verify it. @Mutating is the opposite promise.

      Notes:

      • The attribute is read from the annotation that supplies the operation's method (or, when the method is inferred from the Java method name, from the nearest @RestOp). A subclass that re-declares the method therefore also re-declares whether it is a read: read=true on an overridden annotation that names its own method is replaced along with that method. read=true on another @RestOp in the chain that names no method would be silently ignored, so it fails the resource when its operations are assembled.
      • read=true fails the resource when the method is POST, PUT, PATCH, DELETE, CONNECT, "*" or "RRPC", or when the Java method is also @Mutating. On a safe method it is redundant and has no effect.
      • A CSRF or loopback boundary filter still judges a request on the method it claims, so behind a boundary a GET ?method=VIEW is treated as a write. Prefer path-based links (/view/{file}) for reads.

      See Also:

      Returns:
      The annotation value.
      Since:
      10.0.0
      Default:
      false
    • roleGuard

      Role guard.

      An expression defining if a user with the specified roles are allowed to access this method.

      Example:

      public class MyResource extends BasicRestServlet { @RestOp( method=GET, path="/foo", roleGuard="ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)" ) public Object doGet() { } }

      Notes:

      • Supports any of the following expression constructs:
        • "foo" - Single arguments.
        • "foo,bar,baz" - Multiple OR'ed arguments.
        • "foo | bar | baz" - Multiple OR'ed arguments, pipe syntax.
        • "foo || bar || baz" - Multiple OR'ed arguments, Java-OR syntax.
        • "fo*" - Patterns including '*' and '?'.
        • "fo* & *oo" - Multiple AND'ed arguments, ampersand syntax.
        • "fo* && *oo" - Multiple AND'ed arguments, Java-AND syntax.
        • "fo* || (*oo || bar)" - Parenthesis.
      • AND operations take precedence over OR operations (as expected).
      • Whitespace is ignored.
      • null or empty expressions always match as false.
      • If patterns are used, you must specify the list of declared roles using rolesDeclared().
      • Supports REST Server SVL Variables (e.g. "${L:my.localized.variable}").
      • When defined on parent/child classes and methods, ALL guards within the hierarchy must pass.
      Returns:
      The annotation value.
      Default:
      ""
    • rolesDeclared

      Declared roles.

      A comma-delimited list of all possible user roles.

      Used in conjunction with roleGuard() is used with patterns.

      Example:

      public class MyResource extends BasicRestServlet { @RestOp( method=GET, path="/foo", rolesDeclared="ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL", roleGuard="ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)" ) public Object doGet() { } }

      Returns:
      The annotation value.
      Default:
      ""
    • serializers

      Specifies the serializers for marshalling POJOs into response bodies for this method.

      Serializer are used to convert POJOs to HTTP response bodies.
      Any of the Juneau framework serializers can be used in this setting.
      The serializer selected is based on the request Accept header matched against the values returned by the following method using a best-match algorithm:

      This value overrides serializers specified at the class level using Rest.serializers(). The SerializerSet.Inherit class can be used to include values from the parent class.

      Example:

      // Define a REST resource that can produce JSON and HTML. @Rest( serializers={ JsonParser.class, HtmlParser.class } ) public class MyResource { // Define a REST method that can also produce XML. @RestOp( method=POST, parsers={ SerializerSet.Inherit.class, XmlParser.class } ) public void doPost(MyBean bean) { ... } }

      For programmatic equivalents, contribute a SerializerSet bean via @Bean(name="serializers") (use methodScope to scope to specific operation methods).

      See Also:

      Returns:
      The annotation value.
      Default:
      {}
    • summary

      Optional summary for the exposed API.

      This summary is used in the following locations:

      • The value returned by Operation.getSummary() in the auto-generated swagger.
      • The "${RS:operationSummary}" variable.
      • The summary of the method in the Swagger page.

      Notes:

      • Corresponds to the swagger field /paths/{path}/{method}/summary.
      • Supports REST Server SVL Variables (e.g. "${L:my.localized.variable}").
      Returns:
      The annotation value.
      Default:
      ""
    • 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:

      @RestOp( method=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.'}", "}" } )

      Notes:

      • The format is juneau-bean-swagger-v2.
        Multiple lines are concatenated with newlines.
      • The starting and ending '{'/'}' characters around the entire value are optional.
      • These values are superimposed on top of any Swagger JSON file present for the resource in the classpath.
      • Supports REST Server SVL Variables (e.g. "${L:my.localized.variable}").

      See Also:

      Returns:
      The annotation value.
      Default:
      @org.apache.juneau.rest.server.OpSwagger
    • value

      REST method name and path.

      Can be used to provide a shortened combined form for the method() and path() values.

      The following examples are considered equivalent.

      // Normal form @RestOp(method=PUT, path="/{propertyName}") // Shortened form @RestOp("PUT /{propertyName}")

      Notes:

      • The path portion is optional.
      Returns:
      The annotation value.
      Default:
      ""