0
# CDAP System Application API
1

2
CDAP System Application API provides interfaces and abstract classes for building system services that run in the CDAP (Cask Data Application Platform) system namespace. This library enables development of system-level applications with enhanced privileges for table creation, namespace administration, and worker task execution.
3

4
## Package Information
5

6
- **Package Name**: cdap-system-app-api
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven `pom.xml`:
10

11
```xml
12
<dependency>
13
  <groupId>io.cdap.cdap</groupId>
14
  <artifactId>cdap-system-app-api</artifactId>
15
  <version>6.11.0</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
import io.cdap.cdap.api.SystemTableConfigurer;
23
import io.cdap.cdap.api.service.AbstractSystemService;
24
import io.cdap.cdap.api.service.SystemServiceContext;
25
import io.cdap.cdap.api.service.SystemServiceConfigurer;
26
import io.cdap.cdap.api.service.http.AbstractSystemHttpServiceHandler;
27
import io.cdap.cdap.api.service.http.SystemHttpServiceContext;
28
import io.cdap.cdap.api.service.worker.RunnableTask;
29
import io.cdap.cdap.api.service.worker.RunnableTaskRequest;
30
```
31

32
## Basic Usage
33

34
```java
35
import io.cdap.cdap.api.service.AbstractSystemService;
36
import io.cdap.cdap.api.service.SystemServiceConfigurer;
37
import io.cdap.cdap.api.service.SystemServiceContext;
38
import io.cdap.cdap.spi.data.StructuredTableSpecification;
39

40
// Create a system service
41
public class MySystemService extends AbstractSystemService {
42
  @Override
43
  public void configure(SystemServiceConfigurer configurer) {
44
    setName("my-system-service");
45
    setDescription("A system service example");
46
    
47
    // Create system tables
48
    StructuredTableSpecification tableSpec = StructuredTableSpecification.builder()
49
      .withId("my-system-table")
50
      .withFields(/* field definitions */)
51
      .build();
52
    createTable(tableSpec);
53
  }
54

55
  @Override
56
  protected void startUp() throws Exception {
57
    // Service initialization
58
  }
59

60
  @Override
61
  protected void shutDown() throws Exception {
62
    // Service cleanup
63
  }
64
}
65
```
66

67
## Architecture
68

69
The CDAP System Application API is organized around several key architectural components:
70

71
- **System Services**: Base classes and interfaces for creating system-level services that operate with elevated privileges in the CDAP system namespace
72
- **HTTP Services**: Specialized system service handlers for creating web-based APIs and HTTP endpoints with system-level access
73
- **Worker Tasks**: Framework for executing remote tasks on worker nodes with full system context and capabilities
74
- **System Configuration**: Interfaces for configuring system tables and namespace-level operations
75
- **Exception Handling**: Specialized exception classes for handling errors in remote task execution and system operations
76

77
All system functionality is restricted to applications deployed in the system namespace and provides capabilities beyond those available to regular user applications.
78

79
## Capabilities
80

81
### System Services
82

83
Core system service functionality for creating services that run with elevated privileges in the CDAP system namespace. Includes abstract base classes and configuration interfaces.
84

85
```java { .api }
86
public abstract class AbstractSystemService 
87
    extends AbstractService<SystemServiceConfigurer, SystemServiceContext> {
88
  protected void createTable(StructuredTableSpecification tableSpecification);
89
}
90

91
public interface SystemServiceConfigurer 
92
    extends ServiceConfigurer, SystemTableConfigurer {
93
}
94

95
public interface SystemServiceContext 
96
    extends ServiceContext, TransactionRunner, SystemNamespaceAdmin {
97
}
98
```
99

100
[System Services](./system-services.md)
101

102
### HTTP Services
103

104
System-level HTTP service handlers for creating web APIs and HTTP endpoints with enhanced system privileges and namespace access.
105

106
```java { .api }
107
public abstract class AbstractSystemHttpServiceHandler 
108
    extends AbstractHttpServiceHandler<SystemHttpServiceContext, SystemHttpServiceConfigurer> {
109
  protected void createTable(StructuredTableSpecification tableSpecification);
110
}
111

112
public interface SystemHttpServiceContext 
113
    extends HttpServiceContext, TransactionRunner, SystemNamespaceAdmin {
114
  byte[] runTask(RunnableTaskRequest runnableTaskRequest) throws Exception;
115
  boolean isRemoteTaskEnabled();
116
  ContextAccessEnforcer getContextAccessEnforcer();
117
  Map<String, String> evaluateMacros(String namespace, Map<String, String> properties, 
118
                                    MacroEvaluator evaluator, MacroParserOptions options) 
119
                                    throws InvalidMacroException;
120
}
121
```
122

123
[HTTP Services](./http-services.md)
124

125
### Worker Tasks
126

127
Remote task execution framework allowing system services to run tasks on worker nodes with full system context and serializable task parameters.
128

129
```java { .api }
130
public interface RunnableTask {
131
  void run(RunnableTaskContext context) throws Exception;
132
}
133

134
public class RunnableTaskRequest {
135
  public static Builder getBuilder(String taskClassName);
136
  public String getClassName();
137
  public RunnableTaskParam getParam();
138
  public ArtifactId getArtifactId();
139
  public String getNamespace();
140
}
141

142
public class RunnableTaskContext {
143
  public RunnableTaskContext(RunnableTaskRequest taskRequest);
144
  public void writeResult(byte[] data) throws IOException;
145
  public ByteBuffer getResult();
146
}
147
```
148

149
[Worker Tasks](./worker-tasks.md)
150

151
### System Table Configuration
152

153
Interface for creating and managing system-level tables that persist data in the CDAP system namespace.
154

155
```java { .api }
156
public interface SystemTableConfigurer {
157
  void createTable(StructuredTableSpecification tableSpecification);
158
}
159
```
160

161
System table configuration is available through both system services and HTTP services, allowing applications to create persistent storage that is accessible across the entire CDAP system.
162

163
## Types
164

165
```java { .api }
166
// Base exception for remote task execution errors
167
public class RemoteExecutionException extends Exception {
168
  public RemoteExecutionException(RemoteTaskException cause);
169
  public RemoteTaskException getCause();
170
  public static RemoteExecutionException fromBasicThrowable(BasicThrowable basicThrowable);
171
}
172

173
// Captures stack traces from remote task exceptions  
174
public class RemoteTaskException extends Exception {
175
  public RemoteTaskException(String remoteExceptionClassName, String message, Throwable cause);
176
  public String getRemoteExceptionClassName();
177
}
178

179
// Parameter wrapper for runnable task requests
180
public class RunnableTaskParam {
181
  public RunnableTaskParam(String simpleParam, RunnableTaskRequest embeddedTaskRequest);
182
  public String getSimpleParam();
183
  public RunnableTaskRequest getEmbeddedTaskRequest();
184
}
185
```