1 package com.guinetik.rr.http;
2
3 import com.guinetik.rr.request.RequestSpec;
4
5 /**
6 * Core interface for HTTP request execution in RocketRest.
7 *
8 * <p>This abstraction allows different HTTP client implementations while maintaining
9 * a consistent API. The default implementation uses Java's {@code HttpURLConnection},
10 * but custom implementations can be provided.
11 *
12 * <h2>Implementations</h2>
13 * <ul>
14 * <li>{@link DefaultHttpClient} - Synchronous client using HttpURLConnection</li>
15 * <li>{@link AsyncHttpClient} - Wraps any RocketClient for async execution</li>
16 * <li>{@link FluentHttpClient} - Returns {@link com.guinetik.rr.result.Result} instead of exceptions</li>
17 * <li>{@link CircuitBreakerClient} - Decorator adding circuit breaker resilience</li>
18 * <li>{@link MockRocketClient} - For testing without real HTTP calls</li>
19 * </ul>
20 *
21 * <h2>Creating Clients</h2>
22 * <pre class="language-java"><code>
23 * // Via factory (recommended)
24 * RocketClient client = RocketClientFactory.builder("https://api.example.com")
25 * .withOptions(options)
26 * .withCircuitBreaker(5, 30000)
27 * .build();
28 *
29 * // Execute request
30 * RequestSpec<Void, User> request = RequestBuilder.get("/users/1")
31 * .responseType(User.class)
32 * .build();
33 *
34 * User user = client.execute(request);
35 * </code></pre>
36 *
37 * <h2>Custom Implementation</h2>
38 * <pre class="language-java"><code>
39 * public class OkHttpRocketClient implements RocketClient {
40 * private final OkHttpClient okHttp = new OkHttpClient();
41 *
42 * {@literal @}Override
43 * public <Req, Res> Res execute(RequestSpec<Req, Res> spec) {
44 * // Implement using OkHttp
45 * }
46 * // ... other methods
47 * }
48 * </code></pre>
49 *
50 * @author guinetik <guinetik@gmail.com>
51 * @see RocketClientFactory
52 * @see DefaultHttpClient
53 * @since 1.0.0
54 */
55 public interface RocketClient {
56
57 /**
58 * Executes an HTTP request based on the provided request specification.
59 *
60 * @param <Req> The type of the request body.
61 * @param <Res> The type of the response.
62 * @param requestSpec The specification of the request to be executed.
63 * @return The response object.
64 * @throws RocketRestException If an error occurs during the request execution.
65 */
66 <Req, Res> Res execute(RequestSpec<Req, Res> requestSpec) throws RocketRestException;
67
68 /**
69 * Sets the SSL context to be used for HTTPS requests.
70 *
71 * @param sslContext The SSL context to use.
72 */
73 void configureSsl(javax.net.ssl.SSLContext sslContext);
74
75 void setBaseUrl(String baseUrl);
76 }