0
# System Services
1

2
Core system service functionality for creating services that run with elevated privileges in the CDAP system namespace. System services can create tables, access all namespaces, and perform operations not available to regular user services.
3

4
## Capabilities
5

6
### AbstractSystemService
7

8
Abstract base class for system services that can only be deployed in the system namespace.
9

10
```java { .api }
11
/**
12
 * Abstract class for system services. System services can only be used in 
13
 * applications that are deployed in the system namespace.
14
 */
15
@Beta
16
public abstract class AbstractSystemService 
17
    extends AbstractService<SystemServiceConfigurer, SystemServiceContext> {
18
  
19
  /**
20
   * Creates a system table that conforms to the given table specification 
21
   * when the application is deployed.
22
   * @param tableSpecification the specification for the system table
23
   */
24
  protected void createTable(StructuredTableSpecification tableSpecification);
25
}
26
```
27

28
**Usage Example:**
29

30
```java
31
import io.cdap.cdap.api.service.AbstractSystemService;
32
import io.cdap.cdap.api.service.SystemServiceConfigurer;
33
import io.cdap.cdap.spi.data.StructuredTableSpecification;
34

35
public class MySystemService extends AbstractSystemService {
36
  @Override
37
  public void configure(SystemServiceConfigurer configurer) {
38
    setName("my-system-service");
39
    setDescription("Example system service");
40
    
41
    // Create a system table
42
    StructuredTableSpecification tableSpec = StructuredTableSpecification.builder()
43
      .withId("system-metadata")
44
      .withFields(/* field definitions */)
45
      .build();
46
    createTable(tableSpec);
47
  }
48

49
  @Override
50
  protected void startUp() throws Exception {
51
    // Service startup logic
52
  }
53

54
  @Override
55
  protected void shutDown() throws Exception {
56
    // Service shutdown logic
57
  }
58
}
59
```
60

61
### SystemServiceConfigurer
62

63
Configurer interface for system application services with capabilities beyond those available to user services.
64

65
```java { .api }
66
/**
67
 * Configurer for system application services. Allows additional capabilities 
68
 * beyond those available to user services.
69
 */
70
@Beta
71
public interface SystemServiceConfigurer extends ServiceConfigurer, SystemTableConfigurer {
72
  // Inherits all methods from ServiceConfigurer and SystemTableConfigurer
73
}
74
```
75

76
### SystemServiceContext
77

78
Service context for system services with enhanced capabilities including transaction running and namespace administration.
79

80
```java { .api }
81
/**
82
 * A System ServiceContext that exposes capabilities beyond those available 
83
 * to service contexts for user services.
84
 */
85
public interface SystemServiceContext extends ServiceContext, TransactionRunner, SystemNamespaceAdmin {
86
  // Inherits all methods from ServiceContext, TransactionRunner, and SystemNamespaceAdmin
87
}
88
```
89

90
### SystemNamespaceAdmin
91

92
Interface providing namespace administration capabilities for system services.
93

94
```java { .api }
95
/**
96
 * Interface for listing all namespaces for system service.
97
 */
98
public interface SystemNamespaceAdmin {
99
  /**
100
   * Lists all the namespaces.
101
   * @return list of namespace summaries
102
   * @throws Exception if listing namespaces fails
103
   */
104
  List<NamespaceSummary> listNamespaces() throws Exception;
105
}
106
```
107

108
**Usage Example:**
109

110
```java
111
import io.cdap.cdap.api.service.SystemServiceContext;
112
import io.cdap.cdap.proto.NamespaceSummary;
113

114
public class NamespaceManagerService extends AbstractSystemService {
115
  @Override
116
  protected void startUp() throws Exception {
117
    SystemServiceContext context = getContext();
118
    
119
    // List all namespaces
120
    List<NamespaceSummary> namespaces = context.listNamespaces();
121
    for (NamespaceSummary namespace : namespaces) {
122
      // Process each namespace
123
      LOG.info("Found namespace: {}", namespace.getName());
124
    }
125
  }
126
}
127
```
128

129
### SystemTableConfigurer
130

131
Interface for creating system tables during application deployment.
132

133
```java { .api }
134
/**
135
 * Allows registering system tables for creation.
136
 */
137
@Beta
138
public interface SystemTableConfigurer {
139
  /**
140
   * Creates a system table that conforms to the given specification when 
141
   * application is deployed.
142
   * @param tableSpecification the table specification
143
   */
144
  void createTable(StructuredTableSpecification tableSpecification);
145
}
146
```
147

148
**Usage Example:**
149

150
```java
151
import io.cdap.cdap.api.SystemTableConfigurer;
152
import io.cdap.cdap.spi.data.StructuredTableSpecification;
153
import io.cdap.cdap.spi.data.table.field.FieldType;
154
import io.cdap.cdap.spi.data.table.field.Fields;
155

156
public void configureSystemTable(SystemTableConfigurer configurer) {
157
  StructuredTableSpecification tableSpec = StructuredTableSpecification.builder()
158
    .withId("system-audit-log")
159
    .withFields(
160
      Fields.stringField("timestamp"),
161
      Fields.stringField("user_id"),
162
      Fields.stringField("action"),
163
      Fields.stringField("details")
164
    )
165
    .withPrimaryKeys("timestamp", "user_id")
166
    .withIndexes("action")
167
    .build();
168
    
169
  configurer.createTable(tableSpec);
170
}
171
```
172

173
## Important Notes
174

175
- All system services must be deployed in the **system namespace** only
176
- System services have elevated privileges not available to user services
177
- API classes marked with `@Beta` annotation are subject to change
178
- System services inherit all capabilities from regular CDAP services plus additional system-level operations
179
- Table creation occurs during application deployment, not at runtime