0
# Configuration and Connection Management
1

2
Configuration classes provide the foundation for connecting to CDAP instances. They handle connection settings, SSL configuration, authentication, timeouts, and custom HTTP headers.
3

4
## ConnectionConfig
5

6
Manages connection information to a CDAP instance including hostname, port, SSL settings, and API path configuration.
7

8
```java { .api }
9
public class ConnectionConfig {
10
    // Constructors
11
    public ConnectionConfig(ConnectionConfig config);
12
    public ConnectionConfig(String hostname, Integer port, boolean sslEnabled);
13
    public ConnectionConfig(String hostname, Integer port, boolean sslEnabled, String apiPath);
14
    
15
    // URI resolution methods
16
    public URI getURI();
17
    public String getFullHost();
18
    public URI resolveURI(String path);
19
    public URI resolveURI(String apiVersion, String path);
20
    public URI resolveNamespacedURI(NamespaceId namespace, String apiVersion, String path);
21
    
22
    // Property accessors
23
    public String getHostname();
24
    public Integer getPort();
25
    public boolean isSSLEnabled();
26
    public String getApiPath();
27
    
28
    // Static factory methods
29
    public static Builder builder();
30
    public static Builder builder(ConnectionConfig connectionConfig);
31
    
32
    // Constants
33
    public static final ConnectionConfig DEFAULT;
34
}
35
```
36

37
### ConnectionConfig.Builder
38

39
```java { .api }
40
public static class Builder {
41
    public Builder setHostname(String hostname);
42
    public Builder setPort(Integer port);
43
    public Builder setSSLEnabled(boolean sslEnabled);
44
    public Builder setApiPath(String apiPath);
45
    public ConnectionConfig build();
46
}
47
```
48

49
### Usage Examples
50

51
```java
52
// Basic connection to local CDAP instance
53
ConnectionConfig local = ConnectionConfig.builder()
54
    .setHostname("localhost")
55
    .setPort(11015)
56
    .setSSLEnabled(false)
57
    .build();
58

59
// Secure connection to remote CDAP instance
60
ConnectionConfig remote = ConnectionConfig.builder()
61
    .setHostname("cdap.company.com")
62
    .setPort(443)
63
    .setSSLEnabled(true)
64
    .setApiPath("/api")
65
    .build();
66

67
// Copy constructor for modifications
68
ConnectionConfig modified = ConnectionConfig.builder(remote)
69
    .setPort(8443)
70
    .build();
71
```
72

73
## ClientConfig
74

75
Comprehensive configuration for the Java client API including HTTP settings, authentication, retry policies, and request customization.
76

77
```java { .api }
78
public class ClientConfig {
79
    // URL resolution methods
80
    public URL resolveURL(String path);
81
    public URL resolveURL(String format, Object... args);
82
    public URL resolveURLV3(String path);
83
    public URL resolveURLNoVersion(String path);
84
    public URL resolveNamespacedURLV3(NamespaceId namespace, String path);
85
    
86
    // HTTP configuration accessors
87
    public HttpRequestConfig getDefaultRequestConfig();
88
    public HttpRequestConfig getUploadRequestConfig();
89
    public int getDefaultReadTimeout();
90
    public int getDefaultConnectTimeout();
91
    public int getUploadReadTimeout();
92
    public int getUploadConnectTimeout();
93
    public int getAppListPageSize();
94
    public Map<String, String> getAdditionalHeaders();
95
    
96
    // Core configuration accessors
97
    public ConnectionConfig getConnectionConfig();
98
    public boolean isVerifySSLCert();
99
    public String getApiVersion();
100
    public int getUnavailableRetryLimit();
101
    
102
    // Authentication accessors
103
    public AccessToken getAccessToken();
104
    public Supplier<AccessToken> getAccessTokenSupplier();
105
    
106
    // Static factory methods
107
    public static ClientConfig getDefault();
108
    public static Builder builder();
109
}
110
```
111

112
### ClientConfig.Builder
113

114
```java { .api }
115
public static class Builder {
116
    // Connection configuration
117
    public Builder setConnectionConfig(ConnectionConfig connectionConfig);
118
    
119
    // SSL configuration
120
    public Builder setVerifySSLCert(boolean verifySSLCert);
121
    
122
    // Timeout configuration
123
    public Builder setUploadReadTimeout(int uploadReadTimeout);
124
    public Builder setUploadConnectTimeout(int uploadConnectTimeout);
125
    public Builder setDefaultReadTimeout(int defaultReadTimeout);
126
    public Builder setDefaultConnectTimeout(int defaultConnectTimeout);
127
    
128
    // Request configuration
129
    public Builder setAppListPageSize(int appListPageSize);
130
    public Builder addAdditionalHeader(String header, String value);
131
    public Builder setUnavailableRetryLimit(int retry);
132
    
133
    // Authentication configuration
134
    public Builder setAccessToken(AccessToken accessToken);
135
    public Builder setAccessToken(Supplier<AccessToken> accessToken);
136
    
137
    // API configuration
138
    public Builder setApiVersion(String apiVersion);
139
    
140
    // Build method
141
    public ClientConfig build();
142
}
143
```
144

145
### Configuration Constants
146

147
```java { .api }
148
// Default timeout values
149
public static final int DEFAULT_READ_TIMEOUT = 15000; // milliseconds
150
public static final int DEFAULT_CONNECT_TIMEOUT = 15000; // milliseconds
151
public static final int DEFAULT_UPLOAD_READ_TIMEOUT = 0; // no timeout
152
public static final int DEFAULT_UPLOAD_CONNECT_TIMEOUT = 0; // no timeout
153

154
// Default retry and pagination settings
155
public static final int DEFAULT_SERVICE_UNAVAILABLE_RETRY_LIMIT = 50;
156
public static final int DEFAULT_APP_LIST_PAGE_SIZE = 25;
157

158
// SSL configuration
159
public static final boolean DEFAULT_VERIFY_SSL_CERTIFICATE = true;
160

161
// API version
162
public static final String DEFAULT_VERSION = "v3";
163
```
164

165
### Usage Examples
166

167
```java
168
// Basic client configuration
169
ClientConfig config = ClientConfig.builder()
170
    .setConnectionConfig(connectionConfig)
171
    .build();
172

173
// Advanced configuration with custom settings
174
ClientConfig advancedConfig = ClientConfig.builder()
175
    .setConnectionConfig(connectionConfig)
176
    .setVerifySSLCert(false) // Disable SSL verification for testing
177
    .setDefaultReadTimeout(30000) // 30 seconds
178
    .setDefaultConnectTimeout(10000) // 10 seconds
179
    .setUploadReadTimeout(300000) // 5 minutes for large uploads
180
    .setAppListPageSize(50) // Larger page size
181
    .setUnavailableRetryLimit(10) // Fewer retries
182
    .addAdditionalHeader("X-Custom-Header", "custom-value")
183
    .build();
184

185
// Configuration with authentication token
186
AccessToken token = new AccessToken("auth-token-value", 3600L, "Bearer");
187
ClientConfig authConfig = ClientConfig.builder()
188
    .setConnectionConfig(connectionConfig)
189
    .setAccessToken(token)
190
    .build();
191

192
// Configuration with dynamic token supplier
193
Supplier<AccessToken> tokenSupplier = () -> {
194
    // Your token refresh logic here
195
    return refreshAuthToken();
196
};
197
ClientConfig dynamicAuthConfig = ClientConfig.builder()
198
    .setConnectionConfig(connectionConfig)
199
    .setAccessToken(tokenSupplier)
200
    .build();
201
```
202

203
## Authentication Configuration
204

205
The client supports various authentication mechanisms through the AccessToken system.
206

207
### AccessToken
208

209
```java { .api }
210
public class AccessToken {
211
    public AccessToken(String value, Long expiresIn, String tokenType);
212
    public String getValue();
213
    public Long getExpiresIn();
214
    public String getTokenType();
215
}
216
```
217

218
### Authentication Examples
219

220
```java
221
// Static token authentication
222
AccessToken staticToken = new AccessToken("your-token-here", 3600L, "Bearer");
223
ClientConfig config = ClientConfig.builder()
224
    .setConnectionConfig(connectionConfig)
225
    .setAccessToken(staticToken)
226
    .build();
227

228
// Dynamic token with supplier for automatic refresh
229
Supplier<AccessToken> tokenSupplier = new Supplier<AccessToken>() {
230
    @Override
231
    public AccessToken get() {
232
        // Implement your token refresh logic
233
        String newToken = authService.refreshToken();
234
        return new AccessToken(newToken, 3600L, "Bearer");
235
    }
236
};
237

238
ClientConfig dynamicConfig = ClientConfig.builder()
239
    .setConnectionConfig(connectionConfig)
240
    .setAccessToken(tokenSupplier)
241
    .build();
242

243
// Lambda-based token supplier
244
ClientConfig lambdaConfig = ClientConfig.builder()
245
    .setConnectionConfig(connectionConfig)
246
    .setAccessToken(() -> new AccessToken(getTokenFromService(), 3600L, "Bearer"))
247
    .build();
248
```
249

250
## Error Handling
251

252
Configuration-related exceptions that may be thrown:
253

254
- **MalformedURLException**: Invalid hostname or port in ConnectionConfig
255
- **DisconnectedException**: Connection lost during configuration validation
256
- **IllegalArgumentException**: Invalid configuration parameters
257

258
```java
259
try {
260
    ConnectionConfig config = ConnectionConfig.builder()
261
        .setHostname("invalid-hostname")
262
        .setPort(-1) // Invalid port
263
        .build();
264
} catch (IllegalArgumentException e) {
265
    System.err.println("Invalid configuration: " + e.getMessage());
266
}
267
```
268

269
## Best Practices
270

271
1. **Use Builder Pattern**: Always use the builder pattern for creating configurations
272
2. **Reuse Configurations**: Create configuration objects once and reuse them across multiple clients
273
3. **Handle Timeouts**: Set appropriate timeout values based on your network conditions
274
4. **SSL in Production**: Always enable SSL verification in production environments
275
5. **Token Management**: Use token suppliers for long-running applications to handle token refresh
276
6. **Connection Pooling**: The underlying HTTP client handles connection pooling automatically
277

278
```java
279
// Good: Reuse configuration across clients
280
ClientConfig config = ClientConfig.builder()
281
    .setConnectionConfig(connectionConfig)
282
    .build();
283

284
ApplicationClient appClient = new ApplicationClient(config);
285
ProgramClient programClient = new ProgramClient(config);
286
DatasetClient datasetClient = new DatasetClient(config);
287

288
// Good: Environment-specific configuration
289
ClientConfig prodConfig = ClientConfig.builder()
290
    .setConnectionConfig(prodConnectionConfig)
291
    .setVerifySSLCert(true)
292
    .setDefaultReadTimeout(30000)
293
    .build();
294

295
ClientConfig devConfig = ClientConfig.builder()
296
    .setConnectionConfig(devConnectionConfig)
297
    .setVerifySSLCert(false) // OK for development
298
    .setDefaultReadTimeout(10000)
299
    .build();
300
```