Package org.apache.juneau.http.remote

Annotation Interface Remote

@Documented @Target(TYPE) @Retention(RUNTIME) @Inherited public @interface Remote
Identifies a proxy against a REST interface.
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    accept
    Interface-level default Accept header (and response parser fallback) for all methods.
    boolean
    allowPrivateUrls
    Opts this interface's absolute @Remote/@Url/baseUrl() targets out of the default deny-private SSRF guardrail, applied to every method on the proxy.
    String
    baseUrl
    Base/host override applied to every request the proxy makes.
    String
    contentType
    Interface-level default request body format (and Content-Type header) for all methods.
    String[]
    formData
    Default request form-data parameters.
    Class<?>
    headerList
    Default request header list.
    String[]
    headers
    Default request headers.
    Class<?>[]
    interceptors
    Default lifecycle interceptors applied to every request the proxy makes.
    String
    path
    REST service path.
    String[]
    queryData
    Default request query parameters.
    int
    retries
    Default maximum number of automatic retry attempts applied to every request the proxy makes.
    boolean
    retryNonIdempotent
    Opts non-idempotent verbs (POST/PATCH) into automatic retries for every method on the proxy.
    boolean
    throwOnError
    Default for throwing a generic exception on an error response, applied to every method on the proxy.
    String
    timeout
    Default per-call response/read timeout applied to every request the proxy makes.
    String
    value
    Alias for path().
    String
    version
    Specifies the client version of this interface.
    String
    versionHeader
    Specifies the client version header name.

  • Element Details

    • headerList

      Class<?> headerList
      Default request header list.

      Specifies a supplier of headers to set on all requests. The value is interpreted by the active REST client: the classic Apache-HttpClient transport accepts subclasses of org.apache.juneau.http.classic.header.HeaderList; other transports may ignore the value.

      Notes:
      • Supplier class must provide a public no-arg constructor.
      • Default Void.class means no default header list is supplied.
      Returns:
      The annotation value.
      Default:
      java.lang.Void.class

    • headers

      String[] headers
      Default request headers.

      Specifies headers to set on all requests.

      Notes:
      Returns:
      The annotation value.
      Default:
      {}

    • queryData

      String[] queryData
      Default request query parameters.

      Specifies always-applied constant query parameters emitted on every request the proxy makes — no corresponding method parameter is required. Each entry uses the "name=value" form (the first '=' separates name from value), mirroring the URL-query convention and the headers() "Name: value" precedent.

      A caller-supplied parameter value for the same name still composes with the constant (the constant is not suppressed). A method-level constant of the same name (see @RemoteOp(queryData=...) and the verb annotations) takes precedence over the interface-level value declared here.

      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
      Default request form-data parameters.

      Specifies always-applied constant form-data fields emitted on every request the proxy makes — no corresponding method parameter is required. Each entry uses the "name=value" form (the first '=' separates name from value), mirroring the form-encoded convention and the headers() "Name: value" precedent.

      A caller-supplied parameter value for the same name still composes with the constant (the constant is not suppressed). A method-level constant of the same name (see @RemoteOp(formData=...) and the verb annotations) takes precedence over the interface-level value declared here.

      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:
      {}

    • path

      String path
      REST service path.
      • An absolute URL.
      • A relative URL interpreted as relative to the root URL defined on the RestClient
      • No path interpreted as the class name (e.g. "http://localhost/root-url/org.foo.MyInterface")
      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • value

      String value
      Alias for path().

      Supports VarResolver.DEFAULT (e.g. "$P{mySystemProperty}").

      Returns:
      The annotation value.
      Default:
      ""

    • baseUrl

      String baseUrl
      Base/host override applied to every request the proxy makes.

      Replaces only the authority+root portion of the request URL — in effect, an annotation-declared substitute for the client's root URL — while preserving the interface base path, the method 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 a method-level baseUrl (see @RemoteOp(baseUrl=...) and the verb annotations), then this interface-level value, 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
      Interface-level default request body format (and Content-Type header) for all methods.

      Names a media type (e.g. "application/xml") used as the default for every method on this interface. 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, the client's default serializer is used but this media type is still sent as the label (supporting vendor media types).

      A method-level RemoteOp.contentType() (or verb-annotation equivalent) overrides this default.

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

    • accept

      String accept
      Interface-level default Accept header (and response parser fallback) for all methods.

      Names a media type (e.g. "application/xml") sent as the default Accept header for every method on this interface. Response parsing remains driven by the response Content-Type; this media type is the fallback parser only when the response is unlabeled or its Content-Type matches no registered parser.

      A method-level RemoteOp.accept() (or verb-annotation equivalent) overrides this default.

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

    • version

      String version
      Specifies the client version of this interface.

      Used to populate the "Client-Version" header that identifies what version of client this is so that the server side can handle older versions accordingly.

      The format of this is a string of the format #[.#[.#[...]] (e.g. "1.2.3").

      The server side then uses an OSGi-version matching pattern to identify which methods to call:

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

      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • versionHeader

      String versionHeader
      Specifies the client version header name.

      The default value is "Client-Version".

      Notes:
      Returns:
      The annotation value.
      Default:
      ""

    • interceptors

      Class<?>[] interceptors
      Default lifecycle interceptors applied to every request the proxy makes.

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

      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
      Default per-call response/read timeout applied to every request the proxy makes.

      Expressed as a duration string (e.g. "30s", "1500ms", "1m") parsed by Juneau's duration parser. A method-level timeout (@RemoteOp/@RemoteGet/...) overrides this default. Connect timeouts remain a client-level setting (not configurable per call).

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

    • retries

      int retries
      Default maximum number of automatic retry attempts applied to every request the proxy makes.

      A value of 0 (the default) disables retries. A positive method-level retries overrides this default. See @RemoteOp(retries=...) for the retry trigger statuses and the (hard) safety gating rules.

      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 non-idempotent verbs (POST/PATCH) into automatic retries for every method on the proxy.

      Has no effect unless retries() (or a method-level 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 default and the method-level value.

      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
      Default for throwing a generic exception on an error response, applied to every method on the proxy.

      When true and the response status is an error (>=400) and no typed exception from the method's throws clause matched, a generic exception is thrown. The effective value is the logical OR of this default and the method-level value. See @RemoteOp(throwOnError=...).

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

    • allowPrivateUrls

      boolean allowPrivateUrls
      Opts this interface's absolute @Remote/@Url/baseUrl() targets out of the default deny-private SSRF guardrail, applied to every method on the proxy.

      By default, an absolute http/https URL supplied via baseUrl(), an @Url parameter, or an already-absolute path()/value() is rejected — both at pre-check time and at connect time via resolved-address pinning, re-checked on every followed redirect — when it targets a loopback, RFC1918/link-local, IPv6 unique-local, or cloud-metadata address. Setting this to true disables that check for local-dev/intranet targets that are intentionally private.

      The effective value is the logical OR of this annotation value, the RestClient builder's allowPrivateUrls(...) setting, and the "RestClient.allowPrivateUrls" system property: any one of the three opting in is sufficient.

      Notes:
      • Honored by both the next-generation engine (RestClient.remote(...)) and the classic engine (RestClient.getRemote(...)).
      • Does not affect the http/https-only scheme guard, which always applies.
      Returns:
      The annotation value.
      Default:
      false