0
# CDAP HBase SPI
1

2
The CDAP HBase SPI (Service Provider Interface) provides abstraction for HBase DDL operations within the CDAP platform. It defines interfaces and descriptors for managing HBase tables, namespaces, column families, and coprocessors through a standardized API with idempotent operations.
3

4
## Package Information
5

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

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

21
## Core Imports
22

23
```java
24
import io.cdap.cdap.spi.hbase.HBaseDDLExecutor;
25
import io.cdap.cdap.spi.hbase.HBaseDDLExecutorContext;
26
import io.cdap.cdap.spi.hbase.TableDescriptor;
27
import io.cdap.cdap.spi.hbase.ColumnFamilyDescriptor;
28
import io.cdap.cdap.spi.hbase.CoprocessorDescriptor;
29
import javax.annotation.Nullable;
30
import java.io.Closeable;
31
import java.io.IOException;
32
import java.util.Map;
33
import java.util.Set;
34
```
35

36
## Basic Usage
37

38
```java
39
import io.cdap.cdap.spi.hbase.*;
40
import java.util.*;
41

42
// Implement the HBaseDDLExecutor interface
43
public class MyHBaseDDLExecutor implements HBaseDDLExecutor {
44
    
45
    @Override
46
    public void initialize(HBaseDDLExecutorContext context) {
47
        // Initialize with context
48
        Map<String, String> properties = context.getProperties();
49
        // Use configuration and properties
50
    }
51
    
52
    @Override
53
    public boolean createNamespaceIfNotExists(String name) throws IOException {
54
        // Create namespace implementation
55
        return true;
56
    }
57
    
58
    // ... implement other methods
59
}
60

61
// Create table descriptor
62
Set<ColumnFamilyDescriptor> families = new HashSet<>();
63
families.add(new ColumnFamilyDescriptor(
64
    "cf1", 
65
    1, 
66
    ColumnFamilyDescriptor.CompressionType.SNAPPY,
67
    ColumnFamilyDescriptor.BloomType.ROW,
68
    Collections.emptyMap()
69
));
70

71
TableDescriptor tableDescriptor = new TableDescriptor(
72
    "my_namespace",
73
    "my_table", 
74
    families,
75
    Collections.emptySet(),
76
    Collections.emptyMap()
77
);
78
```
79

80
## Architecture
81

82
The CDAP HBase SPI is organized around key components:
83

84
- **HBaseDDLExecutor**: Main interface providing idempotent DDL operations for namespaces and tables
85
- **HBaseDDLExecutorContext**: Context object providing configuration and properties to the executor
86
- **Descriptor Classes**: Immutable objects describing HBase entities (tables, column families, coprocessors)
87
- **Service Provider Pattern**: Enables pluggable implementations for different HBase versions and configurations
88

89
## Capabilities
90

91
### HBase DDL Operations
92

93
Core interface providing idempotent HBase Data Definition Language operations for namespaces, tables, and permissions.
94

95
```java { .api }
96
public interface HBaseDDLExecutor extends Closeable {
97
    void initialize(HBaseDDLExecutorContext context);
98
    boolean createNamespaceIfNotExists(String name) throws IOException;
99
    void deleteNamespaceIfExists(String name) throws IOException;
100
    void createTableIfNotExists(TableDescriptor descriptor, @Nullable byte[][] splitKeys) throws IOException;
101
    void enableTableIfDisabled(String namespace, String name) throws IOException;
102
    void disableTableIfEnabled(String namespace, String name) throws IOException;
103
    void modifyTable(String namespace, String name, TableDescriptor descriptor) throws IOException;
104
    void truncateTable(String namespace, String name) throws IOException;
105
    void deleteTableIfExists(String namespace, String name) throws IOException;
106
    void grantPermissions(String namespace, @Nullable String table, Map<String, String> permissions) throws IOException;
107
}
108
```
109

110
### Executor Context
111

112
Context interface providing configuration and properties to HBase DDL executors.
113

114
```java { .api }
115
public interface HBaseDDLExecutorContext {
116
    <T> T getConfiguration();
117
    Map<String, String> getProperties();
118
}
119
```
120

121
### Table Description
122

123
Immutable descriptor class that defines HBase table structure including column families and coprocessors.
124

125
```java { .api }
126
public final class TableDescriptor {
127
    public TableDescriptor(String namespace, String name, Set<ColumnFamilyDescriptor> families, 
128
                          Set<CoprocessorDescriptor> coprocessors, Map<String, String> properties);
129
    public String getNamespace();
130
    public String getName();
131
    public Map<String, ColumnFamilyDescriptor> getFamilies();
132
    public Map<String, CoprocessorDescriptor> getCoprocessors();
133
    public Map<String, String> getProperties();
134
}
135
```
136

137
### Column Family Configuration
138

139
Immutable descriptor class defining HBase column family properties including compression and bloom filters.
140

141
```java { .api }
142
public final class ColumnFamilyDescriptor {
143
    public ColumnFamilyDescriptor(String name, int maxVersions, CompressionType compressionType,
144
                                 BloomType bloomType, Map<String, String> properties);
145
    public String getName();
146
    public int getMaxVersions();
147
    public CompressionType getCompressionType();
148
    public BloomType getBloomType();
149
    public Map<String, String> getProperties();
150
    
151
    public enum CompressionType { LZO, SNAPPY, GZIP, NONE }
152
    public enum BloomType { ROW, ROWCOL, NONE }
153
}
154
```
155

156
### Coprocessor Configuration
157

158
Immutable descriptor class defining HBase coprocessor configuration including class name, path, and priority.
159

160
```java { .api }
161
public final class CoprocessorDescriptor {
162
    public CoprocessorDescriptor(String className, @Nullable String path, int priority, 
163
                                Map<String, String> properties);
164
    public String getClassName();
165
    @Nullable public String getPath();
166
    public int getPriority();
167
    public Map<String, String> getProperties();
168
}
169
```
170

171
## Error Handling
172

173
All HBaseDDLExecutor methods throw `IOException` for remote or network exceptions. Additionally:
174

175
- `deleteNamespaceIfExists()` throws `IllegalStateException` if there are tables in the namespace
176
- `modifyTable()`, `truncateTable()`, and `deleteTableIfExists()` throw `IllegalStateException` if the table is not disabled
177

178
## Usage Examples
179

180
### Creating a Table with Column Families
181

182
```java
183
// Create column family with compression and bloom filter
184
ColumnFamilyDescriptor dataFamily = new ColumnFamilyDescriptor(
185
    "data",
186
    3, // max versions
187
    ColumnFamilyDescriptor.CompressionType.SNAPPY,
188
    ColumnFamilyDescriptor.BloomType.ROW,
189
    Collections.emptyMap()
190
);
191

192
ColumnFamilyDescriptor metaFamily = new ColumnFamilyDescriptor(
193
    "meta",
194
    1, // max versions  
195
    ColumnFamilyDescriptor.CompressionType.GZIP,
196
    ColumnFamilyDescriptor.BloomType.NONE,
197
    Collections.emptyMap()
198
);
199

200
Set<ColumnFamilyDescriptor> families = new HashSet<>();
201
families.add(dataFamily);
202
families.add(metaFamily);
203

204
// Create table descriptor
205
TableDescriptor descriptor = new TableDescriptor(
206
    "analytics",
207
    "user_events",
208
    families,
209
    Collections.emptySet(), // no coprocessors
210
    Collections.singletonMap("MAX_FILESIZE", "10737418240") // 10GB
211
);
212

213
// Create table with split keys
214
byte[][] splitKeys = {
215
    "2023".getBytes(),
216
    "2024".getBytes(),
217
    "2025".getBytes()
218
};
219

220
executor.createTableIfNotExists(descriptor, splitKeys);
221
```
222

223
### Adding Coprocessors
224

225
```java
226
// Define coprocessor
227
CoprocessorDescriptor auditProcessor = new CoprocessorDescriptor(
228
    "com.company.hbase.AuditCoprocessor",
229
    "/path/to/audit-coprocessor.jar",
230
    1000, // priority
231
    Collections.singletonMap("audit.enabled", "true")
232
);
233

234
Set<CoprocessorDescriptor> coprocessors = new HashSet<>();
235
coprocessors.add(auditProcessor);
236

237
// Create table with coprocessor
238
TableDescriptor descriptor = new TableDescriptor(
239
    "audit",
240
    "access_log",
241
    families,
242
    coprocessors,
243
    Collections.emptyMap()
244
);
245

246
executor.createTableIfNotExists(descriptor, null);
247
```
248

249
### Managing Permissions
250

251
```java
252
// Grant permissions to users and groups
253
Map<String, String> permissions = new HashMap<>();
254
permissions.put("alice", "rw");        // read/write for user alice
255
permissions.put("@admins", "arwxc");   // all permissions for admins group
256
permissions.put("@readers", "r");      // read-only for readers group
257

258
// Grant table-level permissions
259
executor.grantPermissions("analytics", "user_events", permissions);
260

261
// Grant namespace-level permissions  
262
executor.grantPermissions("analytics", null, permissions);
263
```
264

265
### Table Lifecycle Management
266

267
```java
268
// Standard table modification workflow
269
String namespace = "analytics";
270
String tableName = "user_events";
271

272
// 1. Disable table
273
executor.disableTableIfEnabled(namespace, tableName);
274

275
// 2. Modify table structure
276
executor.modifyTable(namespace, tableName, newDescriptor);
277

278
// 3. Re-enable table
279
executor.enableTableIfDisabled(namespace, tableName);
280

281
// Truncate table (handles disable/enable internally)
282
executor.truncateTable(namespace, tableName);
283

284
// Delete table (requires table to be disabled first)
285
executor.disableTableIfEnabled(namespace, tableName);
286
executor.deleteTableIfExists(namespace, tableName);
287
```