0
# Namespace Management
1

2
Namespace lifecycle management for multi-tenancy support with metadata persistence and comprehensive administrative operations. The NamespaceStore provides essential functionality for managing isolated environments within the CDAP platform, enabling secure multi-tenant deployments with proper resource isolation.
3

4
## Capabilities
5

6
### Core Namespace Operations
7

8
The primary interface for namespace lifecycle management with complete CRUD operations and metadata handling.
9

10
```java { .api }
11
public interface NamespaceStore {
12
    // Namespace lifecycle operations
13
    NamespaceMeta create(NamespaceMeta metadata) throws NamespaceAlreadyExistsException;
14
    void update(NamespaceMeta metadata) throws NamespaceNotFoundException;
15
    NamespaceMeta get(NamespaceId id) throws NamespaceNotFoundException;
16
    NamespaceMeta delete(NamespaceId id) throws NamespaceNotFoundException, NamespaceCannotBeDeletedException;
17
    List<NamespaceMeta> list();
18
    
19
    // Existence checks
20
    boolean hasNamespace(NamespaceId id);
21
}
22
```
23

24
### Namespace Store Implementations
25

26
Different implementations of the NamespaceStore for various deployment scenarios and storage requirements.
27

28
```java { .api }
29
// Default persistent namespace store implementation
30
public class DefaultNamespaceStore implements NamespaceStore {
31
    // Full-featured namespace management with persistent storage backend
32
}
33

34
// In-memory implementation for testing and development
35
public class InMemoryNamespaceStore implements NamespaceStore {
36
    // Fast in-memory namespace operations for testing scenarios
37
}
38
```
39

40
### Namespace Metadata and Configuration
41

42
Comprehensive namespace metadata structure with configuration options for resource limits, security, and custom properties.
43

44
```java { .api }
45
// Namespace metadata container
46
public final class NamespaceMeta {
47
    public static Builder builder();
48
    
49
    public NamespaceId getNamespaceId();
50
    public String getName();
51
    public String getDescription();
52
    public NamespaceConfig getConfig();
53
    public long getCreationTimeMillis();
54
    public Map<String, String> getProperties();
55
    
56
    public static class Builder {
57
        public Builder setName(String name);
58
        public Builder setDescription(String description);
59
        public Builder setConfig(NamespaceConfig config);
60
        public Builder setProperties(Map<String, String> properties);
61
        public Builder setProperty(String key, String value);
62
        public NamespaceMeta build();
63
    }
64
}
65

66
// Namespace configuration options
67
public final class NamespaceConfig {
68
    public static Builder builder();
69
    
70
    public String getSchedulerQueueName();
71
    public String getRootDirectory();
72
    public String getHbaseNamespace();
73
    public String getPrincipal();
74
    public String getKeytabURI();
75
    public Map<String, String> getExploreProperties();
76
    public Map<String, String> getHiveProperties();
77
    
78
    public static class Builder {
79
        public Builder setSchedulerQueueName(String queueName);
80
        public Builder setRootDirectory(String rootDirectory);
81
        public Builder setHbaseNamespace(String hbaseNamespace);
82
        public Builder setPrincipal(String principal);
83
        public Builder setKeytabURI(String keytabURI);
84
        public Builder setExploreProperties(Map<String, String> properties);
85
        public Builder setHiveProperties(Map<String, String> properties);
86
        public NamespaceConfig build();
87
    }
88
}
89
```
90

91
## Usage Examples
92

93
### Basic Namespace Management
94

95
```java
96
// Access namespace store (typically injected)
97
NamespaceStore namespaceStore = // ... obtain instance
98

99
// Create a new namespace with basic configuration
100
NamespaceMeta namespaceMeta = NamespaceMeta.builder()
101
    .setName("analytics")
102
    .setDescription("Analytics and data science workspace")
103
    .setProperty("owner", "data-team")
104
    .setProperty("environment", "production")
105
    .setProperty("cost-center", "engineering")
106
    .build();
107

108
try {
109
    NamespaceMeta created = namespaceStore.create(namespaceMeta);
110
    System.out.println("Created namespace: " + created.getName());
111
    System.out.println("Creation time: " + new Date(created.getCreationTimeMillis()));
112
} catch (NamespaceAlreadyExistsException e) {
113
    System.out.println("Namespace already exists: " + e.getMessage());
114
}
115

116
// Retrieve namespace information
117
NamespaceId namespaceId = NamespaceId.of("analytics");
118
try {
119
    NamespaceMeta retrieved = namespaceStore.get(namespaceId);
120
    System.out.println("Namespace: " + retrieved.getName());
121
    System.out.println("Description: " + retrieved.getDescription());
122
    System.out.println("Properties: " + retrieved.getProperties());
123
} catch (NamespaceNotFoundException e) {
124
    System.out.println("Namespace not found: " + e.getMessage());
125
}
126

127
// Check if namespace exists
128
boolean exists = namespaceStore.hasNamespace(namespaceId);
129
System.out.println("Namespace exists: " + exists);
130
```
131

132
### Advanced Namespace Configuration
133

134
```java
135
// Create namespace with comprehensive configuration
136
NamespaceConfig config = NamespaceConfig.builder()
137
    .setSchedulerQueueName("analytics-queue")
138
    .setRootDirectory("/data/analytics")
139
    .setHbaseNamespace("analytics_hbase")
140
    .setPrincipal("analytics@COMPANY.COM")
141
    .setKeytabURI("file:///etc/security/keytabs/analytics.keytab")
142
    .setExploreProperties(Map.of(
143
        "hive.exec.dynamic.partition", "true",
144
        "hive.exec.dynamic.partition.mode", "nonstrict"
145
    ))
146
    .setHiveProperties(Map.of(
147
        "hive.metastore.warehouse.dir", "/data/analytics/warehouse",
148
        "javax.jdo.option.ConnectionURL", "jdbc:mysql://localhost/analytics_metastore"
149
    ))
150
    .build();
151

152
NamespaceMeta advancedNamespace = NamespaceMeta.builder()
153
    .setName("advanced-analytics")
154
    .setDescription("Advanced analytics environment with custom Hive and HBase configuration")
155
    .setConfig(config)
156
    .setProperty("security-level", "high")
157
    .setProperty("data-classification", "confidential")
158
    .setProperty("backup-enabled", "true")
159
    .setProperty("retention-days", "2555") // 7 years
160
    .build();
161

162
try {
163
    namespaceStore.create(advancedNamespace);
164
    System.out.println("Created advanced namespace with custom configuration");
165
} catch (NamespaceAlreadyExistsException e) {
166
    System.out.println("Advanced namespace already exists");
167
}
168
```
169

170
### Namespace Listing and Management
171

172
```java
173
// List all namespaces
174
List<NamespaceMeta> allNamespaces = namespaceStore.list();
175
System.out.println("Total namespaces: " + allNamespaces.size());
176

177
for (NamespaceMeta namespace : allNamespaces) {
178
    System.out.println("Namespace: " + namespace.getName());
179
    System.out.println("  Description: " + namespace.getDescription());
180
    System.out.println("  Created: " + new Date(namespace.getCreationTimeMillis()));
181
    System.out.println("  Properties: " + namespace.getProperties());
182
    
183
    if (namespace.getConfig() != null) {
184
        NamespaceConfig config = namespace.getConfig();
185
        System.out.println("  Queue: " + config.getSchedulerQueueName());
186
        System.out.println("  Root Dir: " + config.getRootDirectory());
187
        System.out.println("  HBase Namespace: " + config.getHbaseNamespace());
188
    }
189
    System.out.println();
190
}
191

192
// Filter namespaces by properties
193
List<NamespaceMeta> productionNamespaces = allNamespaces.stream()
194
    .filter(ns -> "production".equals(ns.getProperties().get("environment")))
195
    .collect(Collectors.toList());
196

197
System.out.println("Production namespaces: " + productionNamespaces.size());
198
```
199

200
### Namespace Updates and Maintenance
201

202
```java
203
// Update namespace metadata
204
NamespaceId namespaceId = NamespaceId.of("analytics");
205
try {
206
    NamespaceMeta existing = namespaceStore.get(namespaceId);
207
    
208
    // Create updated metadata with new properties
209
    NamespaceMeta updated = NamespaceMeta.builder()
210
        .setName(existing.getName())
211
        .setDescription("Updated: Analytics and machine learning workspace")
212
        .setConfig(existing.getConfig())
213
        .setProperties(existing.getProperties())
214
        .setProperty("last-updated", String.valueOf(System.currentTimeMillis()))
215
        .setProperty("updated-by", "admin-user")
216
        .setProperty("version", "2.0")
217
        .build();
218
    
219
    namespaceStore.update(updated);
220
    System.out.println("Updated namespace: " + namespaceId.getNamespace());
221
    
222
} catch (NamespaceNotFoundException e) {
223
    System.out.println("Cannot update - namespace not found: " + e.getMessage());
224
}
225

226
// Namespace maintenance operations
227
public void performNamespaceMaintenance() {
228
    List<NamespaceMeta> namespaces = namespaceStore.list();
229
    
230
    for (NamespaceMeta namespace : namespaces) {
231
        // Check if namespace needs cleanup
232
        long creationTime = namespace.getCreationTimeMillis();
233
        long daysSinceCreation = (System.currentTimeMillis() - creationTime) / (1000 * 60 * 60 * 24);
234
        
235
        // Add maintenance properties
236
        if (daysSinceCreation > 30) {
237
            NamespaceMeta maintained = NamespaceMeta.builder()
238
                .setName(namespace.getName())
239
                .setDescription(namespace.getDescription())
240
                .setConfig(namespace.getConfig())
241
                .setProperties(namespace.getProperties())
242
                .setProperty("maintenance-check", String.valueOf(System.currentTimeMillis()))
243
                .setProperty("days-active", String.valueOf(daysSinceCreation))
244
                .build();
245
            
246
            try {
247
                namespaceStore.update(maintained);
248
                System.out.println("Updated maintenance info for: " + namespace.getName());
249
            } catch (NamespaceNotFoundException e) {
250
                System.out.println("Namespace disappeared during maintenance: " + namespace.getName());
251
            }
252
        }
253
    }
254
}
255
```
256

257
### Namespace Deletion and Cleanup
258

259
```java
260
// Safe namespace deletion with checks
261
public boolean safeDeleteNamespace(NamespaceId namespaceId) {
262
    try {
263
        // Check if namespace exists
264
        if (!namespaceStore.hasNamespace(namespaceId)) {
265
            System.out.println("Namespace does not exist: " + namespaceId.getNamespace());
266
            return false;
267
        }
268
        
269
        // Get namespace info before deletion
270
        NamespaceMeta namespace = namespaceStore.get(namespaceId);
271
        System.out.println("Deleting namespace: " + namespace.getName());
272
        System.out.println("Description: " + namespace.getDescription());
273
        
274
        // Perform deletion
275
        NamespaceMeta deleted = namespaceStore.delete(namespaceId);
276
        System.out.println("Successfully deleted namespace: " + deleted.getName());
277
        return true;
278
        
279
    } catch (NamespaceNotFoundException e) {
280
        System.out.println("Namespace not found during deletion: " + e.getMessage());
281
        return false;
282
    } catch (NamespaceCannotBeDeletedException e) {
283
        System.out.println("Namespace cannot be deleted: " + e.getMessage());
284
        System.out.println("Reason: " + e.getCause());
285
        return false;
286
    }
287
}
288

289
// Bulk namespace cleanup
290
public void cleanupTestNamespaces() {
291
    List<NamespaceMeta> namespaces = namespaceStore.list();
292
    
293
    for (NamespaceMeta namespace : namespaces) {
294
        // Identify test namespaces
295
        if (namespace.getName().startsWith("test-") || 
296
            "test".equals(namespace.getProperties().get("environment"))) {
297
            
298
            NamespaceId namespaceId = NamespaceId.of(namespace.getName());
299
            System.out.println("Cleaning up test namespace: " + namespace.getName());
300
            
301
            if (safeDeleteNamespace(namespaceId)) {
302
                System.out.println("Successfully removed test namespace: " + namespace.getName());
303
            }
304
        }
305
    }
306
}
307
```
308

309
### Multi-tenant Namespace Management
310

311
```java
312
// Create tenant-specific namespaces
313
public void setupTenantNamespaces(String tenantId, String tenantName) {
314
    // Development namespace
315
    NamespaceMeta devNamespace = NamespaceMeta.builder()
316
        .setName(tenantId + "-dev")
317
        .setDescription("Development environment for " + tenantName)
318
        .setProperty("tenant-id", tenantId)
319
        .setProperty("tenant-name", tenantName)
320
        .setProperty("environment", "development")
321
        .setProperty("data-retention-days", "30")
322
        .build();
323
    
324
    // Staging namespace
325
    NamespaceMeta stagingNamespace = NamespaceMeta.builder()
326
        .setName(tenantId + "-staging")
327
        .setDescription("Staging environment for " + tenantName)
328
        .setProperty("tenant-id", tenantId)
329
        .setProperty("tenant-name", tenantName)
330
        .setProperty("environment", "staging")
331
        .setProperty("data-retention-days", "90")
332
        .build();
333
    
334
    // Production namespace with advanced configuration
335
    NamespaceConfig prodConfig = NamespaceConfig.builder()
336
        .setSchedulerQueueName(tenantId + "-prod")
337
        .setRootDirectory("/data/tenants/" + tenantId + "/prod")
338
        .setHbaseNamespace(tenantId + "_prod")
339
        .build();
340
    
341
    NamespaceMeta prodNamespace = NamespaceMeta.builder()
342
        .setName(tenantId + "-prod")
343
        .setDescription("Production environment for " + tenantName)
344
        .setConfig(prodConfig)
345
        .setProperty("tenant-id", tenantId)
346
        .setProperty("tenant-name", tenantName)
347
        .setProperty("environment", "production")
348
        .setProperty("data-retention-days", "2555") // 7 years
349
        .setProperty("backup-enabled", "true")
350
        .build();
351
    
352
    try {
353
        namespaceStore.create(devNamespace);
354
        namespaceStore.create(stagingNamespace);
355
        namespaceStore.create(prodNamespace);
356
        
357
        System.out.println("Created tenant namespaces for: " + tenantName);
358
    } catch (NamespaceAlreadyExistsException e) {
359
        System.out.println("Some namespaces already exist for tenant: " + tenantId);
360
    }
361
}
362

363
// Get namespaces for a specific tenant
364
public List<NamespaceMeta> getTenantNamespaces(String tenantId) {
365
    return namespaceStore.list().stream()
366
        .filter(ns -> tenantId.equals(ns.getProperties().get("tenant-id")))
367
        .collect(Collectors.toList());
368
}
369
```
370

371
## Types
372

373
```java { .api }
374
// Core namespace types
375
public final class NamespaceId extends EntityId {
376
    public static final NamespaceId DEFAULT = new NamespaceId("default");
377
    public static final NamespaceId SYSTEM = new NamespaceId("system");
378
    
379
    public static NamespaceId of(String namespace);
380
    public String getNamespace();
381
    
382
    // Factory methods for child entities
383
    public ApplicationId app(String application);
384
    public DatasetId dataset(String dataset);
385
    public StreamId stream(String stream);
386
    public DatasetModuleId datasetModule(String module);
387
    public DatasetTypeId datasetType(String type);
388
}
389

390
// Namespace metadata
391
public final class NamespaceMeta {
392
    public NamespaceId getNamespaceId();
393
    public String getName();
394
    public String getDescription();
395
    public NamespaceConfig getConfig();
396
    public long getCreationTimeMillis();
397
    public Map<String, String> getProperties();
398
    
399
    public static Builder builder();
400
    
401
    public static class Builder {
402
        public Builder setName(String name);
403
        public Builder setDescription(String description);
404
        public Builder setConfig(NamespaceConfig config);
405
        public Builder setProperties(Map<String, String> properties);
406
        public Builder setProperty(String key, String value);
407
        public NamespaceMeta build();
408
    }
409
}
410

411
// Namespace configuration
412
public final class NamespaceConfig {
413
    public String getSchedulerQueueName();
414
    public String getRootDirectory();
415
    public String getHbaseNamespace();
416
    public String getPrincipal();
417
    public String getKeytabURI();
418
    public Map<String, String> getExploreProperties();
419
    public Map<String, String> getHiveProperties();
420
    
421
    public static Builder builder();
422
    
423
    public static class Builder {
424
        public Builder setSchedulerQueueName(String queueName);
425
        public Builder setRootDirectory(String rootDirectory);
426
        public Builder setHbaseNamespace(String hbaseNamespace);
427
        public Builder setPrincipal(String principal);
428
        public Builder setKeytabURI(String keytabURI);
429
        public Builder setExploreProperties(Map<String, String> properties);
430
        public Builder setHiveProperties(Map<String, String> properties);
431
        public NamespaceConfig build();
432
    }
433
}
434

435
// Exception types
436
public class NamespaceAlreadyExistsException extends Exception {
437
    public NamespaceAlreadyExistsException(String namespace);
438
    public NamespaceAlreadyExistsException(String namespace, Throwable cause);
439
}
440

441
public class NamespaceNotFoundException extends Exception {
442
    public NamespaceNotFoundException(String namespace);
443
    public NamespaceNotFoundException(String namespace, Throwable cause);
444
}
445

446
public class NamespaceCannotBeDeletedException extends Exception {
447
    public NamespaceCannotBeDeletedException(String namespace, String reason);
448
    public NamespaceCannotBeDeletedException(String namespace, String reason, Throwable cause);
449
}
450
```