Run bounded concurrent HTTP fetches in Java

Implement a batch fetcher for at most 100 URLs. It must run no more than maxConcurrency blocking requests at once, preserve input order in the returned results, enforce both a per-request timeout and an overall batch timeout, cancel unfinished work, and release its executor.

3 URLs, maxConcurrency=2 -> at most 2 active requests
responses complete C, A, B -> results are returned A, B, C
overall timeout expires -> unfinished entries are reported as timed out

• Accept 1 to 100 URLs and maxConcurrency from 1 to 16.
• Use a fixed-size executor for the blocking calls.
• Preserve input ordering regardless of completion ordering.
• Restore the interrupted flag if the coordinating thread is interrupted.
• Do not leave executor threads running after the method returns.

1. Validate the batch and concurrency bounds before creating resources.
2. Build one Callable<FetchResult> per input URL with an HttpRequest timeout.
3. Use timed invokeAll; its returned futures keep task-list order and unfinished tasks are cancelled.
4. Translate success, cancellation, and execution failure into explicit result values.
5. Always call shutdownNow in finally; interruption must also restore the thread flag.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.*;

public final class BatchFetcher {
    public record FetchResult(URI uri, Integer status, String body, String error) {}

    public static List<FetchResult> fetch(
            List<URI> uris, int maxConcurrency,
            Duration requestTimeout, Duration batchTimeout) {
        if (uris.isEmpty() || uris.size() > 100) throw new IllegalArgumentException("uris");
        if (maxConcurrency < 1 || maxConcurrency > 16) throw new IllegalArgumentException("maxConcurrency");

        var client = HttpClient.newHttpClient();
        var pool = Executors.newFixedThreadPool(maxConcurrency);
        try {
            List<Callable<FetchResult>> tasks = uris.stream().map(uri ->
                (Callable<FetchResult>) () -> {
                    var request = HttpRequest.newBuilder(uri).timeout(requestTimeout).GET().build();
                    var response = client.send(request, HttpResponse.BodyHandlers.ofString());
                    return new FetchResult(uri, response.statusCode(), response.body(), null);
                }).toList();

            var futures = pool.invokeAll(tasks, batchTimeout.toMillis(), TimeUnit.MILLISECONDS);
            var results = new ArrayList<FetchResult>(uris.size());
            for (int i = 0; i < futures.size(); i++) {
                try {
                    results.add(futures.get(i).get());
                } catch (CancellationException e) {
                    results.add(new FetchResult(uris.get(i), null, null, "timed out"));
                } catch (ExecutionException e) {
                    results.add(new FetchResult(uris.get(i), null, null,
                            e.getCause().getClass().getSimpleName()));
                }
            }
            return List.copyOf(results);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException("batch interrupted", e);
        } finally {
            pool.shutdownNow();
        }
    }
}

Task setup and result assembly are O(n). At most maxConcurrency blocking requests execute at once, while O(n) tasks and results are retained for the batch.

• The overall deadline may cancel a request before its individual timeout.
• A non-2xx response is still an HTTP response; business policy decides whether it is an error.
• Duplicate URLs are separate input positions and therefore produce separate results.
• A caller interruption aborts coordination and triggers task cancellation.

• Use a local stub server and an active-request counter to prove the concurrency ceiling.
• Return responses out of order and verify result positions match inputs.
• Make one endpoint exceed the batch deadline and verify it is cancelled and marked timed out.
• Interrupt the coordinator and verify the interrupt flag and executor cleanup.

• Creating one thread per URL ignores the concurrency requirement.
• Collecting results as they finish loses input ordering.
• Only configuring a request timeout leaves the whole batch without a deadline.
• Swallowing InterruptedException breaks cooperative cancellation.