0
# Core Interfaces
1

2
The core interfaces define the fundamental contracts for data source operations in Sentinel DataSource Extension. These interfaces provide the foundation for all readable and writable data source implementations.
3

4
## Capabilities
5

6
### ReadableDataSource Interface
7

8
The `ReadableDataSource` interface is responsible for retrieving configurations in a read-only manner. It supports generic type parameters for both source and target data types.
9

10
```java { .api }
11
/**
12
 * The readable data source is responsible for retrieving configs (read-only).
13
 * @param <S> source data type
14
 * @param <T> target data type
15
 */
16
public interface ReadableDataSource<S, T> {
17
    
18
    /**
19
     * Load data from data source as the target type.
20
     * @return the target data
21
     * @throws Exception IO or other error occurs
22
     */
23
    T loadConfig() throws Exception;
24
    
25
    /**
26
     * Read original data from the data source.
27
     * @return the original data
28
     * @throws Exception IO or other error occurs
29
     */
30
    S readSource() throws Exception;
31
    
32
    /**
33
     * Get SentinelProperty of the data source.
34
     * @return the property for dynamic updates
35
     */
36
    SentinelProperty<T> getProperty();
37
    
38
    /**
39
     * Close the data source.
40
     * @throws Exception IO or other error occurs
41
     */
42
    void close() throws Exception;
43
}
44
```
45

46
**Usage Examples:**
47

48
```java
49
// Example: Custom database-backed readable data source
50
public class DatabaseReadableDataSource implements ReadableDataSource<ResultSet, List<FlowRule>> {
51
    private final String connectionUrl;
52
    private final Converter<ResultSet, List<FlowRule>> converter;
53
    
54
    @Override
55
    public List<FlowRule> loadConfig() throws Exception {
56
        ResultSet rs = readSource();
57
        return converter.convert(rs);
58
    }
59
    
60
    @Override
61
    public ResultSet readSource() throws Exception {
62
        Connection conn = DriverManager.getConnection(connectionUrl);
63
        PreparedStatement stmt = conn.prepareStatement("SELECT * FROM flow_rules");
64
        return stmt.executeQuery();
65
    }
66
    
67
    @Override
68
    public SentinelProperty<List<FlowRule>> getProperty() {
69
        return property;
70
    }
71
    
72
    @Override
73
    public void close() throws Exception {
74
        // Close database connections
75
    }
76
}
77
```
78

79
### WritableDataSource Interface
80

81
The `WritableDataSource` interface provides write capability to data sources, enabling dynamic rule updates and configuration persistence.
82

83
```java { .api }
84
/**
85
 * Interface of writable data source support.
86
 * @param <T> data type
87
 */
88
public interface WritableDataSource<T> {
89
    
90
    /**
91
     * Write the value to the data source.
92
     * @param value value to write
93
     * @throws Exception IO or other error occurs
94
     */
95
    void write(T value) throws Exception;
96
    
97
    /**
98
     * Close the data source.
99
     * @throws Exception IO or other error occurs
100
     */
101
    void close() throws Exception;
102
}
103
```
104

105
**Usage Examples:**
106

107
```java
108
// Example: Using file writable data source
109
Converter<List<FlowRule>, String> encoder = rules -> 
110
    JSON.toJSONString(rules, true);
111

112
WritableDataSource<List<FlowRule>> writableDs = 
113
    new FileWritableDataSource<>("/sentinel/rules.json", encoder);
114

115
// Write new rules
116
List<FlowRule> newRules = Arrays.asList(
117
    new FlowRule().setResource("GET:/api/users").setCount(100),
118
    new FlowRule().setResource("GET:/api/orders").setCount(50)
119
);
120

121
writableDs.write(newRules);
122
```
123

124
### Converter Interface
125

126
The `Converter` interface enables transformation between different data types, providing flexibility in data format handling.
127

128
```java { .api }
129
/**
130
 * Convert an object from source type S to target type T.
131
 * @param <S> source type
132
 * @param <T> target type
133
 */
134
public interface Converter<S, T> {
135
    
136
    /**
137
     * Convert source to the target type.
138
     * @param source the source object
139
     * @return the target object
140
     */
141
    T convert(S source);
142
}
143
```
144

145
**Usage Examples:**
146

147
```java
148
// JSON string to FlowRule list converter
149
Converter<String, List<FlowRule>> jsonConverter = source -> {
150
    if (source == null || source.trim().isEmpty()) {
151
        return new ArrayList<>();
152
    }
153
    return JSON.parseArray(source, FlowRule.class);
154
};
155

156
// FlowRule list to JSON string converter
157
Converter<List<FlowRule>, String> ruleEncoder = rules -> {
158
    return JSON.toJSONString(rules, true);
159
};
160

161
// XML string to DegradeRule list converter
162
Converter<String, List<DegradeRule>> xmlConverter = source -> {
163
    DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
164
    Document doc = builder.parse(new ByteArrayInputStream(source.getBytes()));
165
    
166
    List<DegradeRule> rules = new ArrayList<>();
167
    NodeList ruleNodes = doc.getElementsByTagName("rule");
168
    
169
    for (int i = 0; i < ruleNodes.getLength(); i++) {
170
        Element ruleElement = (Element) ruleNodes.item(i);
171
        DegradeRule rule = new DegradeRule();
172
        rule.setResource(ruleElement.getAttribute("resource"));
173
        rule.setCount(Double.parseDouble(ruleElement.getAttribute("count")));
174
        rules.add(rule);
175
    }
176
    
177
    return rules;
178
};
179
```
180

181
## Integration with Sentinel Property System
182

183
All readable data sources integrate with Sentinel's property system to enable dynamic configuration updates:
184

185
```java
186
// Set up dynamic rule loading
187
ReadableDataSource<String, List<FlowRule>> ds = 
188
    new FileRefreshableDataSource<>("/sentinel/flow-rules.json", jsonConverter);
189

190
// Register property listener for automatic rule updates
191
ds.getProperty().addListener(rules -> {
192
    FlowRuleManager.loadRules(rules);
193
    System.out.println("Flow rules updated: " + rules.size() + " rules loaded");
194
});
195
```
196

197
## Error Handling
198

199
All interface methods that perform I/O operations declare `throws Exception`, allowing implementations to handle various error conditions:
200

201
- **FileNotFoundException**: When source files don't exist
202
- **IOException**: For general I/O errors during read/write operations
203
- **IllegalArgumentException**: For invalid parameters or configurations
204
- **ParseException**: When data conversion fails (implementation-specific)