Package org.apache.juneau.rest.client

Class RestRequest

java.lang.Object
org.apache.juneau.rest.client.RestRequest
public final class RestRequest extends Object
Fluent builder for a single HTTP request.

Obtain instances from the RestClient factory methods (e.g. RestClient.get(String)).

Since:
9.2.1

  • Method Details

    • headers

      public RestRequest headers(HttpHeader... value)
      Adds request headers.
      Parameters:
      value - The headers to add. Must not be null.
      Returns:
      This object.

    • header

      public RestRequest header(String name, String value)
      Adds a request header.
      Parameters:
      name - The header name. Must not be null.
      value - The header value. May be null to omit.
      Returns:
      This object.

    • header

      public RestRequest header(String name, Supplier<String> value)
      Adds a request header with a lazy value.
      Parameters:
      name - The header name. Must not be null.
      value - Supplier for the value. Must not be null.
      Returns:
      This object.

    • noTrace

      public RestRequest noTrace()
      Adds a No-Trace: true header, asking the server to keep the stack trace of a failed call out of its log.

      The server still logs the one-line access record; only the attached exception is omitted.

      Returns:
      This object.

    • hasHeader

      public boolean hasHeader(String name)
      Returns true if a header with the given name (case-insensitive) is already set on this request.

      Used by the next-gen remote-proxy engine to honor the precedence of a caller-supplied @Header parameter over an annotation-declared accept/contentType attribute.

      Parameters:
      name - The header name. Must not be null.
      Returns:
      true if the header is present.

    • queryData

      public RestRequest queryData(HttpPart... value)
      Adds query parameters.
      Parameters:
      value - The parts to add. Must not be null.
      Returns:
      This object.

    • queryData

      public RestRequest queryData(String name, String value)
      Adds a query parameter.
      Parameters:
      name - The parameter name. Must not be null.
      value - The parameter value. May be null to omit.
      Returns:
      This object.

    • queryData

      public RestRequest queryData(String name, Supplier<String> value)
      Adds a query parameter with a lazy value.
      Parameters:
      name - The parameter name. Must not be null.
      value - Supplier for the value. Must not be null.
      Returns:
      This object.

    • formData

      public RestRequest formData(HttpPart... value)
      Adds form fields (for application/x-www-form-urlencoded bodies).
      Parameters:
      value - The parts to add. Must not be null.
      Returns:
      This object.

    • formData

      public RestRequest formData(String name, String value)
      Adds a form field.
      Parameters:
      name - The field name. Must not be null.
      value - The field value. May be null to omit.
      Returns:
      This object.

    • pathData

      public RestRequest pathData(HttpPart... value)
      Adds path variable substitutions for URI templates (e.g. replaces {id} in the URL).
      Parameters:
      value - The path parts to apply. Must not be null.
      Returns:
      This object.

    • pathData

      public RestRequest pathData(String name, Object value)
      Adds a path variable.
      Parameters:
      name - The variable name (without braces). Must not be null.
      value - The replacement value. May be null.
      Returns:
      This object.

    • body

      public RestRequest body(HttpBody value)
      Sets the request body directly from an HttpBody.
      Parameters:
      value - The body. May be null.
      Returns:
      This object.

    • body

      public RestRequest body(Object value) throws IOException
      Sets the request body from an arbitrary Java object.

      The object is first run through the client's body converter chain. The default converters handle: HttpBody (passthrough), InputStream, byte[], and File. Custom converters can be registered on the builder.

      If no converter matches, the object is serialized with the client's explicitly-configured default serializer (RestClient.getDefaultSerializer()) and sent as a string body using the serializer's content type. When no default serializer is configured, an IllegalStateException is raised (there is no implicit JSON fallback) — configure one via RestClient.Builder.defaultSerializer(org.apache.juneau.marshall.serializer.Serializer).

      Parameters:
      value - The body object. May be null to clear the body.
      Returns:
      This object.
      Throws:
      IOException - If a converter fails or the default serializer fails.
      IllegalStateException - If no converter matches and no default serializer is configured on the client.

    • streamBodyEntity

      public RestRequest streamBodyEntity(RecordStreamBody value)
      Sets the request body to a token/record-streaming cursor body.

      Convenience for body(streamBody) that documents streaming intent and avoids a cast. The RecordStreamBody writes directly to the transport output stream during run(), so large payloads are streamed to the wire without being buffered in memory.

      Example:

      client.post("/bulk-upload") .streamBodyEntity(RecordStreamBody.records(w -> { for (Bean b : source()) w.write(b); })) .run();

      Parameters:
      value - The streaming body. Must not be null.
      Returns:
      This object.

    • bodyString

      public RestRequest bodyString(String value)
      Sets the request body to a raw string (UTF-8, text/plain).

      Unlike body(Object), this bypasses the converter chain and sends the string as-is.

      Parameters:
      value - The string body. May be null to clear the body.
      Returns:
      This object.

    • timeout

      public RestRequest timeout(Duration value)
      Sets a per-call response timeout for this request.

      Threaded onto the TransportRequest. Intended as a response timeout; connect timeouts are otherwise a client-level setting.

      Transport support: every built-in transport honors this value, using its native per-request mechanism: the JDK HttpRequest timeout, an Apache HttpClient 4.5 RequestConfig (socket + connect timeout), an Apache HttpClient 5 request-scoped response timeout, an OkHttp per-call read timeout, the Jetty response-header wait, and a simulated handler deadline in the mock transport. On expiry the transport throws a TransportException. When set, it overrides the transport's own default for this request only.

      A non-null value must be positive; zero and negative durations are rejected (matching the JDK HttpRequest.timeout contract) so every transport behaves identically.

      Parameters:
      value - The response timeout. May be null to use the transport default.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If value is zero or negative.

    • remoteUrlPolicy

      public RestRequest remoteUrlPolicy(boolean enforced, boolean allowPrivateUrls)
      Marks this request as a @Remote/@Url call subject to the SSRF guardrail (see org.apache.juneau.http.remote.RemoteUrlPolicy), and records the effective allowPrivateUrls opt-in for it.

      Called by the @Remote-proxy invocation handler; not intended for direct use by ordinary RestClient.get(url)-style calls, which are never policy-covered.

      Parameters:
      enforced - true if this request is policy-covered.
      allowPrivateUrls - true if the allowPrivateUrls opt-in is in effect for this request.
      Returns:
      This object.

    • interceptors

      public RestRequest interceptors(RestCallInterceptor... value)
      Adds per-request lifecycle interceptors.

      These are unioned with the client-level interceptors when the request runs: the client-level (builder) interceptors fire first, then these in the order added. The next-gen remote-proxy engine uses this to layer annotation-declared interface-level then method-level interceptors after the builder-configured ones.

      Parameters:
      value - The interceptors to add. Must not be null.
      Returns:
      This object.

    • isBodyRepeatable

      public boolean isBodyRepeatable()
      Returns true if this request's body can be safely re-sent (retry gating).

      A request with no body is trivially repeatable. Otherwise the answer is delegated to the underlying body's HttpBody.isRepeatable() (or TransportBody.isRepeatable() for a pre-converted body): buffered bodies (string/byte[]/file/serialized POJO) are repeatable; one-shot streaming bodies (InputStream/Reader/piped) are not.

      Returns:
      true if the body is absent or repeatable.

    • getMethod

      public String getMethod()
      Returns the HTTP method for this request (e.g. "GET").
      Returns:
      The method. Never null.

    • getUri

      public URI getUri()
      Returns the fully resolved URI for this request, or null if run() has not been called yet.
      Returns:
      The URI, possibly null.

    • getResolvedHeaders

      public List<TransportHeader> getResolvedHeaders()
      Returns the headers resolved onto the transport request.
      Returns:
      The resolved headers in wire order.

    • getFirstHeader

      public TransportHeader getFirstHeader(String name)
      Returns the first resolved request header with the given name (case-insensitive), or null if absent.

      Reads from getResolvedHeaders() — the finalized, wire-order list — not the pre-conversion header list hasHeader(String) uses internally for its dedup check.

      Parameters:
      name - The header name. Must not be null.
      Returns:
      The first matching header, or null if absent.

    • getCachedContent

      public byte[] getCachedContent()
      Returns request body bytes captured for debug logging (up to the configured body cap).
      Returns:
      Captured request bytes, or null if not captured.

    • getCachedContentLength

      public long getCachedContentLength()
      Returns the total request body length observed during write, or -1 if unknown.
      Returns:
      The total body length.

    • getException

      public Throwable getException()
      Returns the terminal request exception, if any.
      Returns:
      The terminal exception, or null.

    • getExecTime

      public Duration getExecTime()
      Returns the measured request execution time.
      Returns:
      The request execution time, or null if unset.

    • requestId

      public RestRequest requestId(String value)
      Sets the X-Request-Id correlation id for this request (pre-call).

      Sets both the outgoing X-Request-Id header and the stored sent-id field returned by getRequestId(). Use this to propagate a caller-owned correlation id; otherwise the built-in auto-send interceptor mints one at request time (unless disabled via RestClient.Builder.sendRequestId(boolean)).

      Parameters:
      value - The correlation id. Must not be null.
      Returns:
      This object.
      Since:
      10.0.0

    • getRequestId

      public String getRequestId()
      Returns the X-Request-Id correlation id sent on this request.

      Captured at request time (minted by the auto-send interceptor, or the caller-supplied value). Read as a stored field at debug-emit time — never via a live log-context scope.

      Returns:
      The sent correlation id, or null if none was sent (e.g. sendRequestId(false)).
      Since:
      10.0.0

    • run

      public RestResponse run() throws TransportException, RestCallException
      Executes the request and returns the response.

      The caller is responsible for closing the returned RestResponse.

      Returns:
      The response. Never null.
      Throws:
      TransportException - If a network-level error occurs.
      RestCallException - If the response could not be processed.

    • openEventStream

      public SseEventReader openEventStream() throws IOException
      Executes this request and opens a closeable, cancellable cursor over the response as a text/event-stream.

      This executes run(), asserts a 2xx response status, then opens the response body as an event stream. Non-2xx responses throw RestCallException before the body is treated as SSE.

      The response content type is not validated. This is intentional so callers can branch on response type (for example application/json vs text/event-stream) when protocols use both.

      Adds an Accept: text/event-stream header only when neither this request nor inherited client default headers already include Accept.

      The caller owns the returned SseEventReader; closing it also closes the underlying RestResponse (see ResponseBody.asEventStream()). If opening the event stream fails, this method best-effort closes the response before propagating.

      Returns:
      A cursor over the live event stream. Never null.
      Throws:
      IOException - If a transport-level error occurs (typically TransportException), if the response could not be processed (typically RestCallException), or if the response has no body to open a stream over.