Interface RequestExecutionEngine

public interface RequestExecutionEngine
A managed engine for sending many HTTP requests concurrently, subject to its ResourcePool (concurrency, throttling, retries). The run is visible and controllable as a task on the Burp dashboard.

Obtain an instance from Http.createRequestEngine() or Http.createRequestEngine(RequestEngineOptions), then drive it one of three ways:

  • Eager - queue the requests up front, then sendAll().
  • Reactive - queue one or more seed requests, then sendAll(ResponseHandler) and let the handler queue follow-ups as responses arrive.
  • Streaming - supply a source that generates requests lazily on demand, for very large or open-ended runs.

Each sendAll overload optionally takes a per-request Duration timeout; the overloads without one apply a sensible default. The send runs in the background and sendAll returns immediately with a RequestExecution handle - so a long-running send never blocks the caller. Each queued request may carry a correlation label echoed back on its RequestResult.

An engine is single-use: exactly one sendAll call starts its one run. Any further sendAll call (of any overload) throws IllegalStateException; create a new engine for another run.

  • Method Details

    • queue

      void queue(HttpRequest request)
      Add a request to the engine's queue. Equivalent to queue(request, "").
      Parameters:
      request - The full HTTP request to send.

    • queue

      void queue(HttpRequest request, String label)
      Add a request to the engine's queue, tagged with a correlation label that is echoed back on the corresponding RequestResult.label(). The label is opaque to the engine; a null label is normalised to "".
      Parameters:
      request - The full HTTP request to send.
      label - A correlation label; null is treated as "".

    • sendAll

      RequestExecution sendAll()
      Start the run from the eagerly queued requests, using the default per-request timeout. Requests are sent in the background and this method returns immediately with a live RequestExecution handle.
      Returns:
      A live handle to the running send.
      Throws:
      IllegalStateException - if a run has already been started on this engine.

    • sendAll

      RequestExecution sendAll(Duration timeout)
      As sendAll(), with an explicit per-request timeout: a request with no response within timeout is recorded as RequestStatus.TIMED_OUT (and retried per the ResourcePool).
      Parameters:
      timeout - The per-request timeout (positive).
      Returns:
      A live handle to the running send.
      Throws:
      IllegalArgumentException - if timeout is null, zero or negative.
      IllegalStateException - if a run has already been started on this engine.

    • sendAll

      RequestExecution sendAll(ResponseHandler handler)
      Start the run with the default per-request timeout, invoking handler once per request as it completes - serially, in completion order (see ResponseHandler). The handler decides whether each result is kept or dropped and may queue more requests via the RequestExecution it receives. Returns immediately.
      Parameters:
      handler - Invoked for each completed request (except RequestStatus.DROPPED ones).
      Returns:
      A live handle to the running send.
      Throws:
      IllegalStateException - if a run has already been started on this engine.

    • sendAll

      RequestExecution sendAll(ResponseHandler handler, Duration timeout)
      As sendAll(ResponseHandler), with an explicit per-request timeout.
      Parameters:
      handler - Invoked for each completed request (except RequestStatus.DROPPED ones).
      timeout - The per-request timeout (positive).
      Returns:
      A live handle to the running send.
      Throws:
      IllegalArgumentException - if timeout is null, zero or negative.
      IllegalStateException - if a run has already been started on this engine.

    • sendAll

      RequestExecution sendAll(RequestSource source)
      Start a run that pulls its requests lazily from source instead of from a pre-queued list, using the default per-request timeout. The engine asks the source for the next request only when it has capacity to send it, so requests are generated on demand and memory stays bounded regardless of the total count - use this for very large or open-ended runs. Returns immediately.

      A streaming run cannot be combined with eagerly queued requests - use one or the other.

      Parameters:
      source - The lazy source of requests to send.
      Returns:
      A live handle to the running send.
      Throws:
      IllegalStateException - if a run has already been started on this engine, or if requests were already queued on this engine.

    • sendAll

      RequestExecution sendAll(RequestSource source, Duration timeout)
      As sendAll(RequestSource), with an explicit per-request timeout.
      Parameters:
      source - The lazy source of requests to send.
      timeout - The per-request timeout (positive).
      Returns:
      A live handle to the running send.
      Throws:
      IllegalArgumentException - if timeout is null, zero or negative.
      IllegalStateException - if a run has already been started, or requests were already queued.

    • sendAll

      RequestExecution sendAll(RequestSource source, ResponseHandler handler)
      As sendAll(RequestSource), additionally invoking handler once per request as it completes - serially (see ResponseHandler) - using the default per-request timeout. The handler decides whether each result is kept or dropped, which can bound the result set on a large run. Returns immediately.
      Parameters:
      source - The lazy source of requests to send.
      handler - Invoked for each completed request (except RequestStatus.DROPPED ones).
      Returns:
      A live handle to the running send.
      Throws:
      IllegalStateException - if a run has already been started, or requests were already queued.

    • sendAll

      RequestExecution sendAll(RequestSource source, ResponseHandler handler, Duration timeout)
      As sendAll(RequestSource, ResponseHandler), with an explicit per-request timeout.
      Parameters:
      source - The lazy source of requests to send.
      handler - Invoked for each completed request (except RequestStatus.DROPPED ones).
      timeout - The per-request timeout (positive).
      Returns:
      A live handle to the running send.
      Throws:
      IllegalArgumentException - if timeout is null, zero or negative.
      IllegalStateException - if a run has already been started, or requests were already queued.