0
# CDAP Common
1

2
CDAP Common provides core common utilities and abstractions for the CDAP (Cask Data Application Platform) ecosystem. It serves as the foundational library for building data applications on Hadoop, offering comprehensive exception handling, service management, configuration utilities, HTTP services, metadata abstractions, security integration, and various utility classes shared across CDAP components.
3

4
## Package Information
5

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

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

21
## Core Imports
22

23
```java
24
// Core API imports
25
import io.cdap.cdap.api.metrics.MetricsCollectionService;
26
import io.cdap.cdap.api.auditlogging.AuditLogWriter;
27

28
// Common utilities
29
import io.cdap.cdap.common.app.RunIds;
30
import io.cdap.cdap.common.conf.CConfiguration;
31
import io.cdap.cdap.common.conf.Constants;
32
import io.cdap.cdap.common.utils.Networks;
33
import io.cdap.cdap.common.service.Services;
34

35
// Exception handling
36
import io.cdap.cdap.common.*;
37
```
38

39
## Basic Usage
40

41
```java
42
import io.cdap.cdap.common.app.RunIds;
43
import io.cdap.cdap.common.conf.CConfiguration;
44
import io.cdap.cdap.common.conf.Constants;
45
import io.cdap.cdap.common.utils.Networks;
46

47
// Generate unique run IDs
48
RunId runId = RunIds.generate();
49
System.out.println("Generated Run ID: " + runId.toString());
50

51
// Configuration management
52
CConfiguration cConf = CConfiguration.create();
53
String servicePort = cConf.get(Constants.Service.APP_FABRIC_HTTP);
54

55
// Network utilities
56
int randomPort = Networks.getRandomPort();
57
InetAddress resolvedAddress = Networks.resolve("localhost", InetAddress.getLoopbackAddress());
58

59
// Exception handling
60
try {
61
    // Some operation that might fail
62
    performOperation();
63
} catch (Exception e) {
64
    throw new BadRequestException("Invalid request: " + e.getMessage(), e);
65
}
66
```
67

68
## Architecture
69

70
CDAP Common is built around several key architectural patterns:
71

72
- **Service Framework**: Built on Google Guava's Service abstraction with lifecycle management, retry strategies, and service discovery integration
73
- **Configuration Hierarchy**: `CConfiguration` for general settings, `SConfiguration` for secure data, with property stores for dynamic updates
74
- **Exception Mapping**: Comprehensive exception hierarchy mapping to HTTP status codes for consistent REST API responses
75
- **Metrics Integration**: Pluggable metrics collection services with structured tagging and no-op testing implementations
76
- **Security Layers**: Multi-layered security with authentication/authorization abstractions, SSL/TLS utilities, and audit logging
77
- **Extension Points**: Plugin architecture with dynamic class loading, bytecode manipulation, and isolated classloaders
78

79
## Capabilities
80

81
### Exception Handling
82

83
Comprehensive exception hierarchy providing HTTP-status-mapped exceptions and domain-specific error types for consistent error handling across CDAP components.
84

85
```java { .api }
86
// HTTP status exceptions
87
public class BadRequestException extends Exception
88
public class NotFoundException extends Exception  
89
public class ConflictException extends Exception
90
public class ForbiddenException extends Exception
91

92
// Domain-specific exceptions
93
public class ApplicationNotFoundException extends NotFoundException
94
public class DatasetNotFoundException extends NotFoundException
95
public class NamespaceNotFoundException extends NotFoundException
96
```
97

98
[Exception Handling](./exceptions.md)
99

100
### Configuration Management
101

102
Centralized configuration system with hierarchical property management, secure configuration handling, and comprehensive constants for all CDAP settings.
103

104
```java { .api }
105
public class CConfiguration extends Configuration
106
public class SConfiguration extends Configuration
107

108
public final class Constants {
109
    public static final class Service { /* service configurations */ }
110
    public static final class Security { /* security settings */ }
111
    public static final class Metrics { /* metrics configuration */ }
112
}
113
```
114

115
[Configuration](./configuration.md)
116

117
### Service Framework
118

119
Service management utilities built on Google Guava's Service interface, providing lifecycle management with timeout handling and error recovery.
120

121
```java { .api }
122
public class Services {
123
    public static void startAndWait(Service service, long timeout, TimeUnit timeoutUnit) 
124
        throws TimeoutException, InterruptedException, ExecutionException;
125
    public static void startAndWait(Service service, long timeout, TimeUnit timeoutUnit, 
126
        String timeoutErrorMessage) 
127
        throws TimeoutException, InterruptedException, ExecutionException;
128
}
129

130
public interface RetryStrategy {
131
    long nextRetry(int failureCount, long startTime);
132
}
133
```
134

135
[Service Framework](./services.md)
136

137
### Network and Discovery Utilities
138

139
Network utilities for address resolution, port management, and service discovery integration with comprehensive tools for distributed service coordination.
140

141
```java { .api }
142
public final class Networks {
143
    public static InetAddress resolve(String hostname, InetAddress onErrorAddress);
144
    public static int getRandomPort();
145
    public static String getIP(SocketAddress address);
146
    public static void addDiscoverable(CConfiguration cConf, String key, Discoverable discoverable);
147
    public static void removeDiscoverable(CConfiguration cConf, String key, Discoverable discoverable);
148
    public static Set<Discoverable> getDiscoverables(CConfiguration cConf, String key);
149
    public static void setAddress(CConfiguration cConf, String key, InetSocketAddress addr);
150
    public static InetSocketAddress getAddress(CConfiguration cConf, String key);
151
}
152
```
153

154
[Network Utilities](./network.md)
155

156
### HTTP Utilities
157

158
HTTP service building and request/response handling components for creating Netty-based HTTP services with authentication, body handling, and configuration management.
159

160
```java { .api }
161
public class CommonNettyHttpServiceBuilder {
162
    public CommonNettyHttpServiceBuilder setHost(String host);
163
    public CommonNettyHttpServiceBuilder setPort(int port);
164
    public NettyHttpService build();
165
}
166
```
167

168
[HTTP Utilities](./http.md)
169

170
### Security Framework
171

172
Security abstractions including authentication annotations, authorization enforcement, SSL/TLS configuration, and audit logging capabilities.
173

174
```java { .api }
175
@Target({ElementType.METHOD, ElementType.TYPE})
176
@Retention(RetentionPolicy.RUNTIME)
177
public @interface AuthEnforce {
178
    String[] value() default {};
179
}
180

181
public class KeyStores {
182
    public static KeyStore generatedCertKeyStore(SConfiguration sConf, String password);
183
}
184
```
185

186
[Security](./security.md)
187

188
### Logging Framework
189

190
Comprehensive logging framework with context-aware logging, audit trail capabilities, and structured logging utilities for CDAP components.
191

192
```java { .api }
193
public interface LoggingContext {
194
    String getLogPartition();
195
    String getLogPathFragment();
196
}
197

198
public class Loggers {
199
    public static <T> Logger getLogger(Class<T> clazz);
200
}
201
```
202

203
[Logging](./logging.md)
204

205
### Utility Classes
206

207
Collection of utility classes for common operations including file handling, string manipulation, time parsing, hash calculations, run ID generation, and system detection.
208

209
```java { .api }
210
public final class RunIds {
211
    public static RunId generate();
212
    public static RunId fromString(String id);
213
    public static long getTime(RunId runId, TimeUnit timeUnit);
214
}
215

216
public final class FileUtils {
217
    public static void ensureDirectoryExists(File directory) throws IOException;
218
    public static void deleteDirectoryContents(File directory) throws IOException;
219
}
220

221
public class TimeMathParser {
222
    public static long parseTimeInMs(String timeMath) throws IllegalArgumentException;
223
}
224
```
225

226
[Utilities](./utilities.md)
227

228
### I/O Framework
229

230
I/O abstractions including binary encoding/decoding, location management, seekable streams, and various I/O utilities for file and stream processing.
231

232
```java { .api }
233
public interface Codec<T> {
234
    byte[] encode(T object) throws IOException;
235
    T decode(byte[] data) throws IOException;
236
}
237

238
public abstract class SeekableInputStream extends InputStream {
239
    public abstract void seek(long pos) throws IOException;
240
    public abstract long getPos() throws IOException;
241
}
242
```
243

244
[I/O Framework](./io.md)