or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

application-management.mdartifact-management.mdconfiguration.mddata-operations.mddataset-operations.mdindex.mdmetrics-monitoring.mdprogram-control.mdschedule-management.mdsecurity-administration.mdservice-management.md
tile.json

tessl/maven-io-cdap-cdap--cdap-client

CDAP Java Client library providing programmatic APIs for interacting with the CDAP platform

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.cdap.cdap/cdap-client@6.11.x

To install, run

npx @tessl/cli install tessl/maven-io-cdap-cdap--cdap-client@6.11.0

index.mddocs/

CDAP Java Client

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.

Package Information

  • Package Name: cdap-client
  • Package Type: maven
  • Language: Java
  • Group ID: io.cdap.cdap
  • Artifact ID: cdap-client
  • Installation: Add to your Maven pom.xml:
<dependency>
    <groupId>io.cdap.cdap</groupId>
    <artifactId>cdap-client</artifactId>
    <version>6.11.0</version>
</dependency>

Core Imports

// Client classes
import io.cdap.cdap.client.ApplicationClient;
import io.cdap.cdap.client.ArtifactClient;
import io.cdap.cdap.client.ProgramClient;
import io.cdap.cdap.client.DatasetClient;
import io.cdap.cdap.client.ServiceClient;
import io.cdap.cdap.client.MetricsClient;
import io.cdap.cdap.client.ScheduleClient;
import io.cdap.cdap.client.NamespaceClient;
import io.cdap.cdap.client.SecureStoreClient;
import io.cdap.cdap.client.config.ClientConfig;
import io.cdap.cdap.client.config.ConnectionConfig;

// Core data types
import io.cdap.cdap.proto.ApplicationRecord;
import io.cdap.cdap.proto.ApplicationDetail;
import io.cdap.cdap.proto.ProgramRecord;
import io.cdap.cdap.proto.DatasetSpecificationSummary;
import io.cdap.cdap.proto.DatasetMeta;
import io.cdap.cdap.proto.RunRecord;
import io.cdap.cdap.proto.ProgramType;
import io.cdap.cdap.proto.ProgramStatus;
import io.cdap.cdap.proto.artifact.AppRequest;

// ID types
import io.cdap.cdap.proto.id.NamespaceId;
import io.cdap.cdap.proto.id.ApplicationId;
import io.cdap.cdap.proto.id.ProgramId;
import io.cdap.cdap.proto.id.ServiceId;
import io.cdap.cdap.proto.id.DatasetId;
import io.cdap.cdap.proto.id.ArtifactId;

// Exception types
import io.cdap.cdap.common.NotFoundException;
import io.cdap.cdap.common.ApplicationNotFoundException;
import io.cdap.cdap.common.BadRequestException;
import io.cdap.cdap.security.spi.authentication.UnauthenticatedException;
import io.cdap.cdap.security.spi.authorization.UnauthorizedException;

Basic Usage

import io.cdap.cdap.client.ApplicationClient;
import io.cdap.cdap.client.config.ClientConfig;
import io.cdap.cdap.client.config.ConnectionConfig;
import io.cdap.cdap.proto.ApplicationRecord;
import io.cdap.cdap.proto.id.NamespaceId;

// Create connection configuration  
ConnectionConfig connection = ConnectionConfig.builder()
    .setHostname("localhost")
    .setPort(11015)
    .setSSLEnabled(false)
    .build();

// Create client configuration
ClientConfig config = ClientConfig.builder()
    .setConnectionConfig(connection)
    .build();

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

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

System.out.println("Found " + apps.size() + " applications");
for (ApplicationRecord app : apps) {
    System.out.println("- " + app.getName() + " (version: " + app.getAppVersion() + ")");
}

Architecture

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

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

Each client follows consistent patterns:

  • Constructor with ClientConfig for basic usage
  • Constructor with ClientConfig and RESTClient for dependency injection
  • Methods throw common exceptions for network, authentication, and authorization errors
  • Support for both synchronous operations and batch operations where applicable

Capabilities

Configuration and Connection Management

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

public class ConnectionConfig {
    public ConnectionConfig(String hostname, Integer port, boolean sslEnabled);
    public ConnectionConfig(String hostname, Integer port, boolean sslEnabled, String apiPath);
    public URI getURI();
    public String getHostname();
    public Integer getPort();
    public boolean isSSLEnabled();
    public static Builder builder();
}

public class ClientConfig {
    public URL resolveURL(String path);
    public URL resolveURLV3(String path);
    public URL resolveNamespacedURLV3(NamespaceId namespace, String path);
    public ConnectionConfig getConnectionConfig();
    public boolean isVerifySSLCert();
    public AccessToken getAccessToken();
    public static Builder builder();
    public static ClientConfig getDefault();
}

Configuration and Connection Management

Application Management

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

public class ApplicationClient {
    public ApplicationClient(ClientConfig config);
    public List<ApplicationRecord> list(NamespaceId namespace);
    public ApplicationDetail get(ApplicationId appId);
    public void deploy(NamespaceId namespace, File jarFile);
    public void deploy(ApplicationId appId, AppRequest<?> createRequest);
    public void update(ApplicationId appId, AppRequest<?> updateRequest);
    public void delete(ApplicationId app);
    public void upgradeApplication(ApplicationId app);
    public List<ProgramRecord> listPrograms(ApplicationId app);
    public boolean exists(ApplicationId app);
}

Application Management

Artifact Management

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

public class ArtifactClient {
    public ArtifactClient(ClientConfig config);
    public List<ArtifactSummary> list(NamespaceId namespace);
    public ArtifactInfo getArtifactInfo(ArtifactId artifactId);
    public void add(ArtifactId artifactId, Set<ArtifactRange> parentArtifacts, ContentProvider<? extends InputStream> artifactContents);
    public void delete(ArtifactId artifactId);
    public List<String> getPluginTypes(ArtifactId artifactId);
    public List<PluginSummary> getPluginSummaries(ArtifactId artifactId, String pluginType);
    public List<ApplicationClassSummary> getApplicationClasses(NamespaceId namespace);
}

Artifact Management

Program Control and Monitoring

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

public class ProgramClient {
    public ProgramClient(ClientConfig config);
    public void start(ProgramId program);
    public void start(ProgramId program, boolean debug, Map<String, String> runtimeArgs);
    public void stop(ProgramId programId);
    public String getStatus(ProgramId programId);
    public void setWorkerInstances(ProgramId worker, int instances);
    public void setServiceInstances(ServiceId service, int instances);
    public List<RunRecord> getProgramRuns(ProgramId program, String state, long startTime, long endTime, int limit);
    public Map<String, String> getRuntimeArgs(ProgramId program);
    public void setRuntimeArgs(ProgramId program, Map<String, String> runtimeArgs);
}

Program Control and Monitoring

Dataset Operations

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

public class DatasetClient {
    public DatasetClient(ClientConfig config);
    public List<DatasetSpecificationSummary> list(NamespaceId namespace);
    public DatasetMeta get(DatasetId instance);
    public void create(DatasetId instance, DatasetInstanceConfiguration properties);
    public void create(DatasetId instance, String typeName);
    public void update(DatasetId instance, Map<String, String> properties);
    public void delete(DatasetId instance);
    public void truncate(DatasetId instance);
    public Map<String, String> getProperties(DatasetId instance);
    public boolean exists(DatasetId instance);
}

Dataset Operations

Service Management

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

public class ServiceClient {
    public ServiceClient(ClientConfig config);
    public ServiceSpecification get(ProgramId service);
    public List<ServiceHttpEndpoint> getEndpoints(ServiceId service);
    public void checkAvailability(ServiceId service);
    public URL getServiceURL(ServiceId service);
    public URL getVersionedServiceURL(ServiceId service);
    public Map<String, Integer> getRouteConfig(ServiceId serviceId);
    public void storeRouteConfig(ServiceId serviceId, Map<String, Integer> routeConfig);
    public HttpResponse callServiceMethod(ServiceId serviceId, String methodPath);
}

Service Management

Metrics and Monitoring

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

public class MetricsClient {
    public MetricsClient(ClientConfig config);
    public List<MetricTagValue> searchTags(Map<String, String> tags);
    public List<String> searchMetrics(Map<String, String> tags);
    public MetricQueryResult query(Map<String, String> tags, String metric);
    public MetricQueryResult query(Map<String, String> tags, List<String> metrics, List<String> groupBys, String start, String end);
    public RuntimeMetrics getServiceMetrics(ServiceId serviceId);
}

public class MonitorClient {
    public MonitorClient(ClientConfig config);
    public List<SystemServiceMeta> listSystemServices();
    public String getSystemServiceStatus(String serviceName);
    public Map<String, String> getAllSystemServiceStatus();
    public boolean allSystemServicesOk();
    public void setSystemServiceInstances(String serviceName, int instances);
    public int getSystemServiceInstances(String serviceName);
}

Metrics and Monitoring

Schedule Management

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

public class ScheduleClient {
    public ScheduleClient(ClientConfig config);
    public void add(ScheduleId scheduleId, ScheduleDetail detail);
    public void update(ScheduleId scheduleId, ScheduleDetail detail);
    public List<ScheduleDetail> listSchedules(WorkflowId workflow);
    public List<ScheduledRuntime> nextRuntimes(WorkflowId workflow);
    public void suspend(ScheduleId scheduleId);
    public void resume(ScheduleId scheduleId);
    public void delete(ScheduleId scheduleId);
    public String getStatus(ScheduleId scheduleId);
}

Schedule Management

Security and Administration

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

public class NamespaceClient {
    public NamespaceClient(ClientConfig config);
    // Inherits namespace CRUD operations from AbstractNamespaceClient
}

public class SecureStoreClient {
    public SecureStoreClient(ClientConfig config);
    public void createKey(SecureKeyId secureKeyId, SecureKeyCreateRequest keyCreateRequest);
    public String getData(SecureKeyId secureKeyId);
    public SecureStoreMetadata getKeyMetadata(SecureKeyId secureKeyId);
    public void deleteKey(SecureKeyId secureKeyId);
    public List<SecureStoreMetadata> listKeys(NamespaceId namespaceId);
}

public class MetadataClient {
    public MetadataClient(ClientConfig config);
    // Inherits metadata CRUD and search operations from AbstractMetadataClient
}

public class AuthorizationClient {
    public AuthorizationClient(ClientConfig config);
    // Authorization operations
}

Security and Administration

Data Operations and Utilities

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

public class LineageClient {
    public LineageClient(ClientConfig config);
    // Data lineage operations
}

public class PreferencesClient {
    public PreferencesClient(ClientConfig config);
    // Preferences management operations
}

public class DatasetModuleClient {
    public DatasetModuleClient(ClientConfig config);
    // Dataset module management operations
}

public class WorkflowClient {
    public WorkflowClient(ClientConfig config);
    // Workflow management operations
}

Data Operations and Utilities

Common Types

// Core ID types
public class NamespaceId {
    public static final NamespaceId DEFAULT;
    public static NamespaceId of(String namespace);
}

public class ApplicationId {
    public static ApplicationId of(NamespaceId namespace, String application);
    public static ApplicationId of(NamespaceId namespace, String application, String version);
}

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

public class ServiceId {
    public static ServiceId of(ApplicationId application, String service);
}

public class DatasetId {
    public static DatasetId of(NamespaceId namespace, String dataset);
}

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

// Exception types
public class UnauthenticatedException extends Exception {}
public class UnauthorizedException extends Exception {}
public class NotFoundException extends Exception {}
public class ApplicationNotFoundException extends NotFoundException {}
public class DisconnectedException extends RuntimeException {
    public DisconnectedException(ConnectionConfig connectionConfig);
    public ConnectionConfig getConnectionConfig();
}

// Authentication types
public class AccessToken {
    public AccessToken(String token, Long expiresInSeconds, String tokenType);
    public String getValue();
    public Long getExpiresInSeconds();
    public String getTokenType();
}

// Enums
public enum ProgramType {
    MAPREDUCE, WORKFLOW, SERVICE, SPARK, WORKER
}

public enum ProgramStatus {
    PENDING, STARTING, RUNNING, SUSPENDED, RESUMING, COMPLETED, FAILED, KILLED, STOPPED
}

Error Handling

All client methods may throw these common exceptions:

  • IOException: Network connectivity issues
  • UnauthenticatedException: Authentication token invalid or expired
  • UnauthorizedException: Insufficient permissions for the operation
  • NotFoundException: Requested resource does not exist (various subclasses)
  • DisconnectedException: Client disconnected from CDAP instance
  • BadRequestException: Invalid request parameters or state

Always handle these exceptions appropriately in your application code.

Authentication

The client supports various authentication mechanisms through the AccessToken system:

// Token-based authentication
AccessToken token = new AccessToken("your-auth-token", 3600L, "Bearer");
ClientConfig config = ClientConfig.builder()
    .setConnectionConfig(connectionConfig)
    .setAccessToken(token)
    .build();

// Or use AccessTokenSupplier for dynamic token refresh
Supplier<AccessToken> tokenSupplier = () -> refreshAndGetToken();
ClientConfig config = ClientConfig.builder()
    .setConnectionConfig(connectionConfig)
    .setAccessToken(tokenSupplier)
    .build();