0
# Client Framework
1

2
Core interfaces and classes for building client applications that can execute requests against remote services with support for load balancing, retry logic, and configuration management.
3

4
## Capabilities
5

6
### IClient Interface
7

8
The main interface for client implementations that can execute requests.
9

10
```java { .api }
11
/**
12
 * Interface for clients that can execute a single request
13
 * @param <S> the request type, extending ClientRequest
14
 * @param <T> the response type, extending IResponse
15
 */
16
public interface IClient<S extends ClientRequest, T extends IResponse> {
17
    /**
18
     * Executes the request and returns response
19
     * @param request the request to execute
20
     * @param requestConfig configuration for this specific request
21
     * @return the response from the request execution
22
     * @throws Exception if the request execution fails
23
     */
24
    T execute(S request, IClientConfig requestConfig) throws Exception;
25
}
26
```
27

28
### ClientRequest Class
29

30
Immutable object representing a client request with load balancing and retry information.
31

32
```java { .api }
33
/**
34
 * Immutable object representing a common client request suitable for all communication protocols
35
 */
36
public class ClientRequest implements Cloneable {
37
    /**
38
     * Creates a new empty request
39
     */
40
    public ClientRequest();
41
    
42
    /**
43
     * Creates a request with a URI
44
     * @param uri the target URI for the request
45
     */
46
    public ClientRequest(URI uri);
47
    
48
    /**
49
     * Creates a request with URI, load balancer key, and retry flag
50
     * @param uri the target URI for the request
51
     * @param loadBalancerKey key used by load balancer for routing decisions
52
     * @param isRetriable whether this request can be retried on failure
53
     */
54
    public ClientRequest(URI uri, Object loadBalancerKey, boolean isRetriable);
55
    
56
    /**
57
     * Copy constructor
58
     * @param request the request to copy
59
     */
60
    public ClientRequest(ClientRequest request);
61
    
62
    /**
63
     * Returns the request URI
64
     * @return the URI of this request
65
     */
66
    public URI getUri();
67
    
68
    /**
69
     * Returns the load balancer key
70
     * @return the load balancer key, or null if not set
71
     */
72
    public Object getLoadBalancerKey();
73
    
74
    /**
75
     * Returns true if the request is retriable
76
     * @return true if this request can be retried on failure
77
     */
78
    public boolean isRetriable();
79
    
80
    /**
81
     * Creates new request with different URI
82
     * @param newURI the new URI for the request
83
     * @return a new ClientRequest with the specified URI
84
     */
85
    public ClientRequest replaceUri(URI newURI);
86
}
87
```
88

89
**Usage Examples:**
90

91
```java
92
import com.netflix.client.ClientRequest;
93
import java.net.URI;
94

95
// Basic request
96
URI serviceUri = URI.create("http://my-service/api/users");
97
ClientRequest request = new ClientRequest(serviceUri);
98

99
// Request with load balancer key (e.g., user ID for sticky sessions)
100
ClientRequest stickyRequest = new ClientRequest(
101
    serviceUri, 
102
    "user123",  // load balancer key
103
    true        // is retriable
104
);
105

106
// Create modified request with new URI
107
URI newUri = URI.create("http://my-service/api/users/123");
108
ClientRequest modifiedRequest = request.replaceUri(newUri);
109
```
110

111
### IResponse Interface
112

113
Interface defining the contract for response objects returned by client implementations.
114

115
```java { .api }
116
/**
117
 * Response interface for the client framework
118
 */
119
public interface IResponse extends Closeable {
120
    /**
121
     * Returns the response payload
122
     * @return the response payload object
123
     * @throws ClientException if there's an error accessing the payload
124
     */
125
    Object getPayload() throws ClientException;
126
    
127
    /**
128
     * Checks if response has payload
129
     * @return true if the response contains a payload
130
     */
131
    boolean hasPayload();
132
    
133
    /**
134
     * Returns true if response is successful
135
     * @return true if the response indicates success
136
     */
137
    boolean isSuccess();
138
    
139
    /**
140
     * Returns the request URI that generated this response
141
     * @return the original request URI
142
     */
143
    URI getRequestedURI();
144
    
145
    /**
146
     * Returns response headers
147
     * @return map of response headers
148
     */
149
    Map<String, ?> getHeaders();
150
}
151
```
152

153
### IClientConfigAware Interface
154

155
Interface for components that need access to client configuration for initialization.
156

157
```java { .api }
158
/**
159
 * Interface for components that need access to client configuration
160
 */
161
public interface IClientConfigAware {
162
    /**
163
     * Initialize with client configuration
164
     * @param clientConfig the configuration to use for initialization
165
     */
166
    default void initWithNiwsConfig(IClientConfig clientConfig);
167
    
168
    /**
169
     * Initialize with client configuration and factory
170
     * @param clientConfig the configuration to use
171
     * @param factory factory for creating additional objects
172
     */
173
    default void initWithNiwsConfig(IClientConfig clientConfig, Factory factory);
174
    
175
    /**
176
     * Factory interface for creating objects with configuration
177
     */
178
    interface Factory {
179
        /**
180
         * Creates an object of the specified type using configuration
181
         * @param type the type of object to create
182
         * @param config the configuration to use
183
         * @return the created object
184
         * @throws InstantiationException if object cannot be instantiated
185
         * @throws IllegalAccessException if object constructor is not accessible
186
         * @throws ClassNotFoundException if the specified type class is not found
187
         */
188
        Object create(String type, IClientConfig config) 
189
            throws InstantiationException, IllegalAccessException, ClassNotFoundException;
190
    }
191
}
192
```
193

194
### Utils Class
195

196
Utility class providing common operations for client framework.
197

198
```java { .api }
199
/**
200
 * Utility class for common operations
201
 */
202
public class Utils {
203
    /**
204
     * Searches for specific throwable types in exception cause chain
205
     * @param throwableToSearchIn the exception to search through
206
     * @param throwableToSearchFor collection of exception types to find
207
     * @return true if any of the specified throwable types are found in the cause chain
208
     */
209
    public static boolean isPresentAsCause(
210
        Throwable throwableToSearchIn, 
211
        Collection<Class<? extends Throwable>> throwableToSearchFor
212
    );
213
}
214
```
215

216
### VipAddressResolver Interface
217

218
Interface for resolving VIP (Virtual IP) addresses, which are logical names for target server farms.
219

220
```java { .api }
221
/**
222
 * Interface for resolving VIP addresses (logical names for target server farms)
223
 */
224
public interface VipAddressResolver {
225
    /**
226
     * Resolves a VIP address using client configuration
227
     * @param vipAddress the VIP address to resolve
228
     * @param niwsClientConfig client configuration containing resolution context
229
     * @return the resolved address
230
     */
231
    String resolve(String vipAddress, IClientConfig niwsClientConfig);
232
}
233
```
234

235
**Usage Examples:**
236

237
```java
238
import com.netflix.client.*;
239
import com.netflix.client.config.IClientConfig;
240

241
// Example client implementation
242
public class MyHttpClient implements IClient<ClientRequest, MyHttpResponse> {
243
    private final IClientConfig config;
244
    
245
    public MyHttpClient(IClientConfig config) {
246
        this.config = config;
247
    }
248
    
249
    @Override
250
    public MyHttpResponse execute(ClientRequest request, IClientConfig requestConfig) 
251
            throws Exception {
252
        // Implementation would handle HTTP request execution
253
        // using the request URI, load balancer key, etc.
254
        
255
        URI uri = request.getUri();
256
        Object lbKey = request.getLoadBalancerKey();
257
        boolean canRetry = request.isRetriable();
258
        
259
        // Execute HTTP request and return response
260
        return new MyHttpResponse(/* response data */);
261
    }
262
}
263

264
// Example response implementation
265
public class MyHttpResponse implements IResponse {
266
    private final Object payload;
267
    private final boolean success;
268
    private final URI requestUri;
269
    private final Map<String, String> headers;
270
    
271
    @Override
272
    public Object getPayload() throws ClientException {
273
        return payload;
274
    }
275
    
276
    @Override
277
    public boolean hasPayload() {
278
        return payload != null;
279
    }
280
    
281
    @Override
282
    public boolean isSuccess() {
283
        return success;
284
    }
285
    
286
    @Override
287
    public URI getRequestedURI() {
288
        return requestUri;
289
    }
290
    
291
    @Override
292
    public Map<String, ?> getHeaders() {
293
        return headers;
294
    }
295
    
296
    @Override
297
    public void close() throws IOException {
298
        // Clean up resources if needed
299
    }
300
}
301
```