Package org.apache.juneau.http.remote

Annotation Interface RemoteGet

@Documented @Target(METHOD) @Retention(RUNTIME) @Inherited @AnnotationGroup(RemoteOp.class) public @interface RemoteGet
Annotation applied to Java methods on REST proxy interface classes.

Note that this annotation is optional if you do not need to override any of the values.

See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    accept
    Sets the Accept header (and the response parser fallback) for this method's request.
    String
    baseUrl
    Base/host override applied to this method's request.
    String
    contentType
    Selects the request body format (and the Content-Type header) for this method's request.
    String[]
    formData
    Constant request form-data parameters applied to every invocation of this method.
    String[]
    headers
    Constant request headers applied to every invocation of this method.
    Class<?>[]
    interceptors
    Lifecycle interceptors applied to every invocation of this method.
    String
    path
    REST service path.
    String[]
    queryData
    Constant request query parameters applied to every invocation of this method.
    int
    retries
    Maximum number of automatic retry attempts for this method's request.
    boolean
    retryNonIdempotent
    Opts a non-idempotent verb (POST/PATCH) into automatic retries.
    RemoteReturn
    returns
    The value the remote method returns.
    boolean
    throwOnError
    Throws a generic exception when the response status is an error (>=400) and no typed exception from the method's throws clause matched.
    String
    timeout
    Per-call response/read timeout applied to this method's request.
    String
    value
    REST path.

  • Element Details

    • path

      String path
      REST service path.

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

      Example:

      // POST /pet @RemoteGet public Pet getPet(...);

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

      • An absolute URL.
      • A relative URL interpreted as relative to the root URL defined on the RestClient and/or Remote.path().
      • No path.
      Returns:
      The annotation value.
      Default:
      ""

    • returns

      RemoteReturn returns
      The value the remote method returns.
      • RemoteReturn.BODY (default) - The body of the HTTP response converted to a POJO.
        The return type on the Java method can be any of the following:
        • void - Don't parse any response. Note that the method will still throw an exception if an error HTTP status is returned.
        • Any parsable POJO - The body of the response will be converted to the POJO using the parser defined on the RestClient.
        • Any POJO annotated with the @Response annotation. This allows for response beans to be used which also allows for OpenAPI-based parsing and validation.
        • HttpResponse - Returns the raw HttpResponse returned by the inner HttpClient.
        • Reader - Returns access to the raw reader of the response.
        • InputStream - Returns access to the raw input stream of the response.
      • RemoteReturn.STATUS - The HTTP status code on the response.
        The return type on the Java method can be any of the following:
        • int/Integer - The HTTP response code.
        • boolean/Boolean - true if the response code is <400
      Returns:
      The annotation value.
      Default:
      BODY

    • value

      String value
      REST path.

      Can be used to provide a shortened form for the path() value.

      The following examples are considered equivalent.

      // Normal form @RemoteGet(path="/{propertyName}") // Shortened form @RemoteGet("/{propertyName}")

      Returns:
      The annotation value.
      Default:
      ""

    • baseUrl

      String baseUrl
      Base/host override applied to this method's request.

      Replaces only the authority+root portion of the request URL while preserving the interface base path, this method's path, and any {var} templating. For example, with baseUrl="http://other-host", an interface path of "/api" and a method path of "/users/{id}", the effective URL is "http://other-host/api/users/{id}".

      Precedence (most-specific first): an @Url parameter, then this method-level value, then the interface-level default (Remote.baseUrl()), then the client root URL.

      Notes:
      • Supports VarResolver.DEFAULT (e.g. "$S{mySystemProperty}").
      • Only http/https schemes are permitted when the override yields an absolute URL; other schemes are rejected (SSRF guardrail).
      • Honored by both the next-generation engine (RestClient.remote(...)) and the classic engine (RestClient.getRemote(...)), with the same http/https-only scheme guard on both.
      Returns:
      The annotation value.
      Default:
      ""

    • contentType

      String contentType
      Selects the request body format (and the Content-Type header) for this method's request.

      Names a media type (e.g. "application/xml"). The next-generation engine selects the matching registered request serializer from the client's serializer set so the request body bytes are actually written in that format, and sets the Content-Type header to this media type — cleanly replacing the serializer's default content type (exactly one Content-Type header is sent).

      If no registered serializer matches this media type, the client's default serializer is used to write the body but this media type is still sent as the Content-Type label (supporting vendor media types such as "application/vnd.example.v2+json" whose bytes are really the default format).

      Precedence (most-specific first): this method-level value, then the interface-level default (Remote.contentType()). This dedicated attribute takes precedence over a constant Content-Type declared via headers() (since it also drives serializer selection); a genuinely caller-supplied @Header("Content-Type") parameter still takes effect.

      Notes:
      • Honored by both the next-generation engine (RestClient.remote(...)) and the classic engine (RestClient.getRemote(...)).
      Returns:
      The annotation value.
      Default:
      ""

    • accept

      String accept
      Sets the Accept header (and the response parser fallback) for this method's request.

      Names a media type (e.g. "application/xml") sent as the request's Accept header. Response parsing remains driven by the response Content-Type (the server is authoritative about what it actually sent); this media type is used as the fallback parser only when the response is unlabeled or its Content-Type matches no registered parser.

      If no registered parser matches this media type, the client's default parser is used as the fallback.

      Precedence (most-specific first): this method-level value, then the interface-level default (Remote.accept()). This dedicated attribute takes precedence over a constant Accept declared via headers(); a genuinely caller-supplied @Header("Accept") parameter still takes effect. Exactly one Accept header is sent.

      Notes:
      • Honored by both the next-generation engine (RestClient.remote(...)) and the classic engine (RestClient.getRemote(...)).
      Returns:
      The annotation value.
      Default:
      ""

    • headers

      String[] headers
      Constant request headers applied to every invocation of this method.

      Each entry uses the "Name: value" form (the first ':' separates name from value), mirroring Remote.headers(). The header is emitted unconditionally on every call — no corresponding method parameter is required. A caller-supplied parameter value for the same name still composes with the constant (it is not suppressed), and this method-level value takes precedence over an interface-level Remote.headers() constant of the same name.

      Notes:
      • Supports VarResolver.DEFAULT (e.g. "$S{mySystemProperty}").
      • Honored by both the next-generation engine (RestClient.remote(...)) and the classic engine (RestClient.getRemote(...)).
      Returns:
      The annotation value.
      Default:
      {}

    • queryData

      String[] queryData
      Constant request query parameters applied to every invocation of this method.

      Each entry uses the "name=value" form (the first '=' separates name from value). The query parameter is emitted unconditionally on every call — no corresponding method parameter is required. A caller-supplied parameter value for the same name still composes with the constant (it is not suppressed), and this method-level value takes precedence over an interface-level Remote.queryData() constant of the same name.

      Notes:
      • Supports VarResolver.DEFAULT (e.g. "$S{mySystemProperty}").
      • Honored by both the next-generation engine (RestClient.remote(...)) and the classic engine (RestClient.getRemote(...)).
      Returns:
      The annotation value.
      Default:
      {}

    • formData

      String[] formData
      Constant request form-data parameters applied to every invocation of this method.

      Each entry uses the "name=value" form (the first '=' separates name from value). The form-data field is emitted unconditionally on every call — no corresponding method parameter is required. A caller-supplied parameter value for the same name still composes with the constant (it is not suppressed), and this method-level value takes precedence over an interface-level Remote.formData() constant of the same name.

      Notes:
      • Supports VarResolver.DEFAULT (e.g. "$S{mySystemProperty}").
      • Honored by both the next-generation engine (RestClient.remote(...)) and the classic engine (RestClient.getRemote(...)).
      Returns:
      The annotation value.
      Default:
      {}

    • interceptors

      Class<?>[] interceptors
      Lifecycle interceptors applied to every invocation of this method.

      Each class must implement the next-generation RestCallInterceptor SPI and provide a public no-arg constructor. Method-level interceptors run after (closest to the call) any interface-level (Remote.interceptors()) and builder-configured interceptors; the three sets are unioned in the order builder → interface → method.

      Notes:
      • The member type is Class<?>[] (not Class<? extends RestCallInterceptor>[]) because RestCallInterceptor lives in the juneau-rest-client module, which this annotation's module must not depend on; each element is resolved to a RestCallInterceptor at proxy-build time.
      • Honored by the next-generation engine (RestClient.remote(...)) only; the classic engine currently ignores this attribute.
      Returns:
      The annotation value.
      Default:
      {}

    • timeout

      String timeout
      Per-call response/read timeout applied to this method's request.

      Expressed as a duration string (e.g. "30s", "1500ms", "1m") parsed by Juneau's duration parser, and wired to the underlying transport's response timeout. Scalar precedence: this method-level value overrides the interface-level default (Remote.timeout()). Connect timeouts remain a client-level setting.

      Notes:
      • Honored by both the next-generation engine (RestClient.remote(...)) and the classic engine (RestClient.getRemote(...)).
      Returns:
      The annotation value.
      Default:
      ""

    • retries

      int retries
      Maximum number of automatic retry attempts for this method's request.

      A value of 0 (the default) disables retries. Retries are attempted only on connection failures and on retryable HTTP statuses (429 and 5xx), with a short exponential backoff between attempts.

      Safety gating (hard rules):

      Scalar precedence: a positive method-level value overrides the interface-level default (Remote.retries()).

      Notes:
      • Honored by both the next-generation engine (RestClient.remote(...)) and the classic engine (RestClient.getRemote(...)).
      Returns:
      The annotation value.
      Default:
      0

    • retryNonIdempotent

      boolean retryNonIdempotent
      Opts a non-idempotent verb (POST/PATCH) into automatic retries.

      Has no effect unless retries() (or Remote.retries()) is positive. Even when enabled, a request with a non-repeatable body is never retried. The effective value is the logical OR of this method-level value and the interface-level default (Remote.retryNonIdempotent()).

      Notes:
      • Honored by both the next-generation engine (RestClient.remote(...)) and the classic engine (RestClient.getRemote(...)).
      Returns:
      The annotation value.
      Default:
      false

    • throwOnError

      boolean throwOnError
      Throws a generic exception when the response status is an error (>=400) and no typed exception from the method's throws clause matched.

      Composes with the typed-exception mapping: a declared exception type whose status code matches the response is still thrown in preference to the generic exception. Respects the same return-mode gating as the typed mapping. The effective value is the logical OR of this method-level value and the interface-level default (Remote.throwOnError()).

      Notes:
      • Honored by both the next-generation engine (RestClient.remote(...)) and the classic engine (RestClient.getRemote(...)).
      Returns:
      The annotation value.
      Default:
      false