0
# Exception Handling
1

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

4
## Capabilities
5

6
### HTTP Status Exceptions
7

8
Base exceptions that map directly to HTTP status codes for REST API error responses.
9

10
```java { .api }
11
/**
12
 * Exception indicating a bad request (HTTP 400)
13
 */
14
public class BadRequestException extends Exception {
15
    public BadRequestException(String message);
16
    public BadRequestException(String message, Throwable cause);
17
}
18

19
/**
20
 * Exception indicating a resource was not found (HTTP 404)
21
 */
22
public class NotFoundException extends Exception {
23
    public NotFoundException(String message);
24
    public NotFoundException(String message, Throwable cause);
25
}
26

27
/**
28
 * Exception indicating a conflict (HTTP 409)
29
 */
30
public class ConflictException extends Exception {
31
    public ConflictException(String message);
32
    public ConflictException(String message, Throwable cause);
33
}
34

35
/**
36
 * Exception indicating forbidden access (HTTP 403)
37
 */
38
public class ForbiddenException extends Exception {
39
    public ForbiddenException(String message);
40
    public ForbiddenException(String message, Throwable cause);
41
}
42

43
/**
44
 * Exception indicating too many requests (HTTP 429)
45
 */
46
public class TooManyRequestsException extends Exception {
47
    public TooManyRequestsException(String message);
48
    public TooManyRequestsException(String message, Throwable cause);
49
}
50
```
51

52
**Usage Examples:**
53

54
```java
55
import io.cdap.cdap.common.BadRequestException;
56
import io.cdap.cdap.common.NotFoundException;
57

58
// Validate input parameters
59
public void validateInput(String input) throws BadRequestException {
60
    if (input == null || input.trim().isEmpty()) {
61
        throw new BadRequestException("Input cannot be null or empty");
62
    }
63
}
64

65
// Resource lookup
66
public Application findApplication(String appId) throws NotFoundException {
67
    Application app = applicationStore.get(appId);
68
    if (app == null) {
69
        throw new NotFoundException("Application not found: " + appId);
70
    }
71
    return app;
72
}
73
```
74

75
### Service-Level Exceptions
76

77
Exceptions for service-related errors and handler failures.
78

79
```java { .api }
80
/**
81
 * Exception for service-related errors
82
 */
83
public class ServiceException extends Exception {
84
    public ServiceException(String message);
85
    public ServiceException(String message, Throwable cause);
86
}
87

88
/**
89
 * Exception for Netty pipeline handler failures
90
 */
91
public class HandlerException extends Exception {
92
    public HandlerException(String message);
93
    public HandlerException(String message, Throwable cause);
94
}
95
```
96

97
### Application Management Exceptions
98

99
Domain-specific exceptions for CDAP application lifecycle operations.
100

101
```java { .api }
102
/**
103
 * Exception indicating an application was not found
104
 */
105
public class ApplicationNotFoundException extends NotFoundException {
106
    public ApplicationNotFoundException(String message);
107
    public ApplicationNotFoundException(String message, Throwable cause);
108
}
109

110
/**
111
 * Exception indicating an application already exists
112
 */
113
public class ApplicationAlreadyExistsException extends ConflictException {
114
    public ApplicationAlreadyExistsException(String message);
115
    public ApplicationAlreadyExistsException(String message, Throwable cause);
116
}
117

118
/**
119
 * Exception indicating general already-exists condition
120
 */
121
public class AlreadyExistsException extends ConflictException {
122
    public AlreadyExistsException(String message);
123
    public AlreadyExistsException(String message, Throwable cause);
124
}
125
```
126

127
### Artifact Management Exceptions
128

129
Exceptions for CDAP artifact operations including deployment and management.
130

131
```java { .api }
132
/**
133
 * Exception indicating an artifact was not found
134
 */
135
public class ArtifactNotFoundException extends NotFoundException {
136
    public ArtifactNotFoundException(String message);
137
    public ArtifactNotFoundException(String message, Throwable cause);
138
}
139

140
/**
141
 * Exception indicating an artifact already exists
142
 */
143
public class ArtifactAlreadyExistsException extends ConflictException {
144
    public ArtifactAlreadyExistsException(String message);
145
    public ArtifactAlreadyExistsException(String message, Throwable cause);
146
}
147

148
/**
149
 * Exception indicating an invalid artifact
150
 */
151
public class InvalidArtifactException extends BadRequestException {
152
    public InvalidArtifactException(String message);
153
    public InvalidArtifactException(String message, Throwable cause);
154
}
155
```
156

157
### Dataset Management Exceptions
158

159
Exceptions for CDAP dataset operations and dataset module management.
160

161
```java { .api }
162
/**
163
 * Exception indicating a dataset was not found
164
 */
165
public class DatasetNotFoundException extends NotFoundException {
166
    public DatasetNotFoundException(String message);
167
    public DatasetNotFoundException(String message, Throwable cause);
168
}
169

170
/**
171
 * Exception indicating a dataset already exists
172
 */
173
public class DatasetAlreadyExistsException extends ConflictException {
174
    public DatasetAlreadyExistsException(String message);
175
    public DatasetAlreadyExistsException(String message, Throwable cause);
176
}
177

178
/**
179
 * Exception indicating a dataset module was not found
180
 */
181
public class DatasetModuleNotFoundException extends NotFoundException {
182
    public DatasetModuleNotFoundException(String message);
183
    public DatasetModuleNotFoundException(String message, Throwable cause);
184
}
185
```
186

187
### Namespace Management Exceptions
188

189
Exceptions for CDAP namespace operations.
190

191
```java { .api }
192
/**
193
 * Exception indicating a namespace was not found
194
 */
195
public class NamespaceNotFoundException extends NotFoundException {
196
    public NamespaceNotFoundException(String message);
197
    public NamespaceNotFoundException(String message, Throwable cause);
198
}
199

200
/**
201
 * Exception indicating a namespace already exists
202
 */
203
public class NamespaceAlreadyExistsException extends ConflictException {
204
    public NamespaceAlreadyExistsException(String message);
205
    public NamespaceAlreadyExistsException(String message, Throwable cause);
206
}
207
```
208

209
### Security Exceptions
210

211
Exceptions for secure key management operations.
212

213
```java { .api }
214
/**
215
 * Exception indicating a secure key was not found
216
 */
217
public class SecureKeyNotFoundException extends NotFoundException {
218
    public SecureKeyNotFoundException(String message);
219
    public SecureKeyNotFoundException(String message, Throwable cause);
220
}
221

222
/**
223
 * Exception indicating a secure key already exists
224
 */
225
public class SecureKeyAlreadyExistsException extends ConflictException {
226
    public SecureKeyAlreadyExistsException(String message);
227
    public SecureKeyAlreadyExistsException(String message, Throwable cause);
228
}
229
```
230

231
**Usage Examples:**
232

233
```java
234
import io.cdap.cdap.common.*;
235

236
// Application management
237
public void deployApplication(String appId, ApplicationSpec spec) 
238
    throws ApplicationAlreadyExistsException, BadRequestException {
239
    
240
    if (applicationExists(appId)) {
241
        throw new ApplicationAlreadyExistsException("Application already deployed: " + appId);
242
    }
243
    
244
    if (spec == null) {
245
        throw new BadRequestException("Application specification cannot be null");
246
    }
247
    
248
    // Deploy application...
249
}
250

251
// Dataset operations
252
public Dataset createDataset(String datasetId, DatasetSpec spec) 
253
    throws DatasetAlreadyExistsException, InvalidArtifactException {
254
    
255
    if (datasetExists(datasetId)) {
256
        throw new DatasetAlreadyExistsException("Dataset already exists: " + datasetId);
257
    }
258
    
259
    if (!isValidDatasetType(spec.getType())) {
260
        throw new InvalidArtifactException("Invalid dataset type: " + spec.getType());
261
    }
262
    
263
    // Create dataset...
264
}
265

266
// Namespace operations
267
public void deleteNamespace(String namespaceId) throws NamespaceNotFoundException {
268
    if (!namespaceExists(namespaceId)) {
269
        throw new NamespaceNotFoundException("Namespace not found: " + namespaceId);
270
    }
271
    
272
    // Delete namespace...
273
}
274
```