0
# CDAP Java Client
1

2
A comprehensive Java client library for interacting with CDAP (Cask Data Application Platform). The client library provides programmatic access to the full range of CDAP functionality through RESTful API calls, enabling developers to build CDAP-aware applications and management tools without dealing with low-level REST API details.
3

4
## Package Information
5

6
- **Package Name**: cdap-client
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: io.cdap.cdap
10
- **Artifact ID**: cdap-client
11
- **Installation**: Add to your Maven `pom.xml`:
12

13
```xml
14
<dependency>
15
    <groupId>io.cdap.cdap</groupId>
16
    <artifactId>cdap-client</artifactId>
17
    <version>6.11.0</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
// Client classes
25
import io.cdap.cdap.client.ApplicationClient;
26
import io.cdap.cdap.client.ArtifactClient;
27
import io.cdap.cdap.client.ProgramClient;
28
import io.cdap.cdap.client.DatasetClient;
29
import io.cdap.cdap.client.ServiceClient;
30
import io.cdap.cdap.client.MetricsClient;
31
import io.cdap.cdap.client.ScheduleClient;
32
import io.cdap.cdap.client.NamespaceClient;
33
import io.cdap.cdap.client.SecureStoreClient;
34
import io.cdap.cdap.client.config.ClientConfig;
35
import io.cdap.cdap.client.config.ConnectionConfig;
36

37
// Core data types
38
import io.cdap.cdap.proto.ApplicationRecord;
39
import io.cdap.cdap.proto.ApplicationDetail;
40
import io.cdap.cdap.proto.ProgramRecord;
41
import io.cdap.cdap.proto.DatasetSpecificationSummary;
42
import io.cdap.cdap.proto.DatasetMeta;
43
import io.cdap.cdap.proto.RunRecord;
44
import io.cdap.cdap.proto.ProgramType;
45
import io.cdap.cdap.proto.ProgramStatus;
46
import io.cdap.cdap.proto.artifact.AppRequest;
47

48
// ID types
49
import io.cdap.cdap.proto.id.NamespaceId;
50
import io.cdap.cdap.proto.id.ApplicationId;
51
import io.cdap.cdap.proto.id.ProgramId;
52
import io.cdap.cdap.proto.id.ServiceId;
53
import io.cdap.cdap.proto.id.DatasetId;
54
import io.cdap.cdap.proto.id.ArtifactId;
55

56
// Exception types
57
import io.cdap.cdap.common.NotFoundException;
58
import io.cdap.cdap.common.ApplicationNotFoundException;
59
import io.cdap.cdap.common.BadRequestException;
60
import io.cdap.cdap.security.spi.authentication.UnauthenticatedException;
61
import io.cdap.cdap.security.spi.authorization.UnauthorizedException;
62
```
63

64
## Basic Usage
65

66
```java
67
import io.cdap.cdap.client.ApplicationClient;
68
import io.cdap.cdap.client.config.ClientConfig;
69
import io.cdap.cdap.client.config.ConnectionConfig;
70
import io.cdap.cdap.proto.ApplicationRecord;
71
import io.cdap.cdap.proto.id.NamespaceId;
72

73
// Create connection configuration  
74
ConnectionConfig connection = ConnectionConfig.builder()
75
    .setHostname("localhost")
76
    .setPort(11015)
77
    .setSSLEnabled(false)
78
    .build();
79

80
// Create client configuration
81
ClientConfig config = ClientConfig.builder()
82
    .setConnectionConfig(connection)
83
    .build();
84

85
// Create application client
86
ApplicationClient appClient = new ApplicationClient(config);
87

88
// List applications in default namespace
89
NamespaceId namespace = NamespaceId.DEFAULT;
90
List<ApplicationRecord> apps = appClient.list(namespace);
91

92
System.out.println("Found " + apps.size() + " applications");
93
for (ApplicationRecord app : apps) {
94
    System.out.println("- " + app.getName() + " (version: " + app.getAppVersion() + ")");
95
}
96
```
97

98
## Architecture
99

100
The CDAP Java Client follows a modular architecture with specialized client classes for different CDAP services:
101

102
- **Client Configuration**: `ClientConfig` and `ConnectionConfig` provide connection and HTTP settings
103
- **Service Clients**: Individual client classes for each CDAP service (applications, artifacts, programs, etc.)
104
- **REST Client**: `RESTClient` handles HTTP communication with authentication and error handling
105
- **Type Safety**: Strong typing through CDAP proto objects for all API operations
106

107
Each client follows consistent patterns:
108
- Constructor with `ClientConfig` for basic usage
109
- Constructor with `ClientConfig` and `RESTClient` for dependency injection
110
- Methods throw common exceptions for network, authentication, and authorization errors
111
- Support for both synchronous operations and batch operations where applicable
112

113
## Capabilities
114

115
### Configuration and Connection Management
116

117
Foundation classes for configuring client connections to CDAP instances, including SSL settings, authentication, timeouts, and custom headers.
118

119
```java { .api }
120
public class ConnectionConfig {
121
    public ConnectionConfig(String hostname, Integer port, boolean sslEnabled);
122
    public ConnectionConfig(String hostname, Integer port, boolean sslEnabled, String apiPath);
123
    public URI getURI();
124
    public String getHostname();
125
    public Integer getPort();
126
    public boolean isSSLEnabled();
127
    public static Builder builder();
128
}
129

130
public class ClientConfig {
131
    public URL resolveURL(String path);
132
    public URL resolveURLV3(String path);
133
    public URL resolveNamespacedURLV3(NamespaceId namespace, String path);
134
    public ConnectionConfig getConnectionConfig();
135
    public boolean isVerifySSLCert();
136
    public AccessToken getAccessToken();
137
    public static Builder builder();
138
    public static ClientConfig getDefault();
139
}
140
```
141

142
[Configuration and Connection Management](./configuration.md)
143

144
### Application Management
145

146
Comprehensive application lifecycle management including deployment, updating, deletion, and program management. Handle application versions, configurations, and plugin discovery.
147

148
```java { .api }
149
public class ApplicationClient {
150
    public ApplicationClient(ClientConfig config);
151
    public List<ApplicationRecord> list(NamespaceId namespace);
152
    public ApplicationDetail get(ApplicationId appId);
153
    public void deploy(NamespaceId namespace, File jarFile);
154
    public void deploy(ApplicationId appId, AppRequest<?> createRequest);
155
    public void update(ApplicationId appId, AppRequest<?> updateRequest);
156
    public void delete(ApplicationId app);
157
    public void upgradeApplication(ApplicationId app);
158
    public List<ProgramRecord> listPrograms(ApplicationId app);
159
    public boolean exists(ApplicationId app);
160
}
161
```
162

163
[Application Management](./application-management.md)
164

165
### Artifact Management
166

167
Artifact lifecycle operations, plugin discovery, and application class management. Handle artifact deployment, versioning, dependencies, and metadata.
168

169
```java { .api }
170
public class ArtifactClient {
171
    public ArtifactClient(ClientConfig config);
172
    public List<ArtifactSummary> list(NamespaceId namespace);
173
    public ArtifactInfo getArtifactInfo(ArtifactId artifactId);
174
    public void add(ArtifactId artifactId, Set<ArtifactRange> parentArtifacts, ContentProvider<? extends InputStream> artifactContents);
175
    public void delete(ArtifactId artifactId);
176
    public List<String> getPluginTypes(ArtifactId artifactId);
177
    public List<PluginSummary> getPluginSummaries(ArtifactId artifactId, String pluginType);
178
    public List<ApplicationClassSummary> getApplicationClasses(NamespaceId namespace);
179
}
180
```
181

182
[Artifact Management](./artifact-management.md)
183

184
### Program Control and Monitoring
185

186
Program lifecycle control including start, stop, restart operations, status monitoring, instance management, and run history tracking.
187

188
```java { .api }
189
public class ProgramClient {
190
    public ProgramClient(ClientConfig config);
191
    public void start(ProgramId program);
192
    public void start(ProgramId program, boolean debug, Map<String, String> runtimeArgs);
193
    public void stop(ProgramId programId);
194
    public String getStatus(ProgramId programId);
195
    public void setWorkerInstances(ProgramId worker, int instances);
196
    public void setServiceInstances(ServiceId service, int instances);
197
    public List<RunRecord> getProgramRuns(ProgramId program, String state, long startTime, long endTime, int limit);
198
    public Map<String, String> getRuntimeArgs(ProgramId program);
199
    public void setRuntimeArgs(ProgramId program, Map<String, String> runtimeArgs);
200
}
201
```
202

203
[Program Control and Monitoring](./program-control.md)
204

205
### Dataset Operations
206

207
Dataset management including creation, configuration, property management, and data operations like truncation.
208

209
```java { .api }
210
public class DatasetClient {
211
    public DatasetClient(ClientConfig config);
212
    public List<DatasetSpecificationSummary> list(NamespaceId namespace);
213
    public DatasetMeta get(DatasetId instance);
214
    public void create(DatasetId instance, DatasetInstanceConfiguration properties);
215
    public void create(DatasetId instance, String typeName);
216
    public void update(DatasetId instance, Map<String, String> properties);
217
    public void delete(DatasetId instance);
218
    public void truncate(DatasetId instance);
219
    public Map<String, String> getProperties(DatasetId instance);
220
    public boolean exists(DatasetId instance);
221
}
222
```
223

224
[Dataset Operations](./dataset-operations.md)
225

226
### Service Management
227

228
User service interactions including endpoint discovery, availability checking, routing configuration, and direct service method calls.
229

230
```java { .api }
231
public class ServiceClient {
232
    public ServiceClient(ClientConfig config);
233
    public ServiceSpecification get(ProgramId service);
234
    public List<ServiceHttpEndpoint> getEndpoints(ServiceId service);
235
    public void checkAvailability(ServiceId service);
236
    public URL getServiceURL(ServiceId service);
237
    public URL getVersionedServiceURL(ServiceId service);
238
    public Map<String, Integer> getRouteConfig(ServiceId serviceId);
239
    public void storeRouteConfig(ServiceId serviceId, Map<String, Integer> routeConfig);
240
    public HttpResponse callServiceMethod(ServiceId serviceId, String methodPath);
241
}
242
```
243

244
[Service Management](./service-management.md)
245

246
### Metrics and Monitoring
247

248
Metrics querying, system service monitoring, and performance data collection. Search metrics, query time series data, and monitor system health.
249

250
```java { .api }
251
public class MetricsClient {
252
    public MetricsClient(ClientConfig config);
253
    public List<MetricTagValue> searchTags(Map<String, String> tags);
254
    public List<String> searchMetrics(Map<String, String> tags);
255
    public MetricQueryResult query(Map<String, String> tags, String metric);
256
    public MetricQueryResult query(Map<String, String> tags, List<String> metrics, List<String> groupBys, String start, String end);
257
    public RuntimeMetrics getServiceMetrics(ServiceId serviceId);
258
}
259

260
public class MonitorClient {
261
    public MonitorClient(ClientConfig config);
262
    public List<SystemServiceMeta> listSystemServices();
263
    public String getSystemServiceStatus(String serviceName);
264
    public Map<String, String> getAllSystemServiceStatus();
265
    public boolean allSystemServicesOk();
266
    public void setSystemServiceInstances(String serviceName, int instances);
267
    public int getSystemServiceInstances(String serviceName);
268
}
269
```
270

271
[Metrics and Monitoring](./metrics-monitoring.md)
272

273
### Schedule Management
274

275
Schedule creation, management, and workflow scheduling operations. Handle time-based and data-driven scheduling.
276

277
```java { .api }
278
public class ScheduleClient {
279
    public ScheduleClient(ClientConfig config);
280
    public void add(ScheduleId scheduleId, ScheduleDetail detail);
281
    public void update(ScheduleId scheduleId, ScheduleDetail detail);
282
    public List<ScheduleDetail> listSchedules(WorkflowId workflow);
283
    public List<ScheduledRuntime> nextRuntimes(WorkflowId workflow);
284
    public void suspend(ScheduleId scheduleId);
285
    public void resume(ScheduleId scheduleId);
286
    public void delete(ScheduleId scheduleId);
287
    public String getStatus(ScheduleId scheduleId);
288
}
289
```
290

291
[Schedule Management](./schedule-management.md)
292

293
### Security and Administration
294

295
Security operations including namespace management, secure key storage, metadata management, authorization, and administrative functions.
296

297
```java { .api }
298
public class NamespaceClient {
299
    public NamespaceClient(ClientConfig config);
300
    // Inherits namespace CRUD operations from AbstractNamespaceClient
301
}
302

303
public class SecureStoreClient {
304
    public SecureStoreClient(ClientConfig config);
305
    public void createKey(SecureKeyId secureKeyId, SecureKeyCreateRequest keyCreateRequest);
306
    public String getData(SecureKeyId secureKeyId);
307
    public SecureStoreMetadata getKeyMetadata(SecureKeyId secureKeyId);
308
    public void deleteKey(SecureKeyId secureKeyId);
309
    public List<SecureStoreMetadata> listKeys(NamespaceId namespaceId);
310
}
311

312
public class MetadataClient {
313
    public MetadataClient(ClientConfig config);
314
    // Inherits metadata CRUD and search operations from AbstractMetadataClient
315
}
316

317
public class AuthorizationClient {
318
    public AuthorizationClient(ClientConfig config);
319
    // Authorization operations
320
}
321
```
322

323
[Security and Administration](./security-administration.md)
324

325
### Data Operations and Utilities
326

327
Additional data operations including lineage tracking, preferences management, dataset modules, and workflow management.
328

329
```java { .api }
330
public class LineageClient {
331
    public LineageClient(ClientConfig config);
332
    // Data lineage operations
333
}
334

335
public class PreferencesClient {
336
    public PreferencesClient(ClientConfig config);
337
    // Preferences management operations
338
}
339

340
public class DatasetModuleClient {
341
    public DatasetModuleClient(ClientConfig config);
342
    // Dataset module management operations
343
}
344

345
public class WorkflowClient {
346
    public WorkflowClient(ClientConfig config);
347
    // Workflow management operations
348
}
349
```
350

351
[Data Operations and Utilities](./data-operations.md)
352

353
## Common Types
354

355
```java { .api }
356
// Core ID types
357
public class NamespaceId {
358
    public static final NamespaceId DEFAULT;
359
    public static NamespaceId of(String namespace);
360
}
361

362
public class ApplicationId {
363
    public static ApplicationId of(NamespaceId namespace, String application);
364
    public static ApplicationId of(NamespaceId namespace, String application, String version);
365
}
366

367
public class ProgramId {
368
    public static ProgramId of(ApplicationId application, ProgramType type, String program);
369
}
370

371
public class ServiceId {
372
    public static ServiceId of(ApplicationId application, String service);
373
}
374

375
public class DatasetId {
376
    public static DatasetId of(NamespaceId namespace, String dataset);
377
}
378

379
public class ArtifactId {
380
    public static ArtifactId of(NamespaceId namespace, String name, String version);
381
}
382

383
// Exception types
384
public class UnauthenticatedException extends Exception {}
385
public class UnauthorizedException extends Exception {}
386
public class NotFoundException extends Exception {}
387
public class ApplicationNotFoundException extends NotFoundException {}
388
public class DisconnectedException extends RuntimeException {
389
    public DisconnectedException(ConnectionConfig connectionConfig);
390
    public ConnectionConfig getConnectionConfig();
391
}
392

393
// Authentication types
394
public class AccessToken {
395
    public AccessToken(String token, Long expiresInSeconds, String tokenType);
396
    public String getValue();
397
    public Long getExpiresInSeconds();
398
    public String getTokenType();
399
}
400

401
// Enums
402
public enum ProgramType {
403
    MAPREDUCE, WORKFLOW, SERVICE, SPARK, WORKER
404
}
405

406
public enum ProgramStatus {
407
    PENDING, STARTING, RUNNING, SUSPENDED, RESUMING, COMPLETED, FAILED, KILLED, STOPPED
408
}
409
```
410

411
## Error Handling
412

413
All client methods may throw these common exceptions:
414

415
- **IOException**: Network connectivity issues
416
- **UnauthenticatedException**: Authentication token invalid or expired
417
- **UnauthorizedException**: Insufficient permissions for the operation
418
- **NotFoundException**: Requested resource does not exist (various subclasses)
419
- **DisconnectedException**: Client disconnected from CDAP instance
420
- **BadRequestException**: Invalid request parameters or state
421

422
Always handle these exceptions appropriately in your application code.
423

424
## Authentication
425

426
The client supports various authentication mechanisms through the `AccessToken` system:
427

428
```java
429
// Token-based authentication
430
AccessToken token = new AccessToken("your-auth-token", 3600L, "Bearer");
431
ClientConfig config = ClientConfig.builder()
432
    .setConnectionConfig(connectionConfig)
433
    .setAccessToken(token)
434
    .build();
435

436
// Or use AccessTokenSupplier for dynamic token refresh
437
Supplier<AccessToken> tokenSupplier = () -> refreshAndGetToken();
438
ClientConfig config = ClientConfig.builder()
439
    .setConnectionConfig(connectionConfig)
440
    .setAccessToken(tokenSupplier)
441
    .build();
442
```