0
# Sentinel DataSource Extension
1

2
Sentinel DataSource Extension provides extensible data source implementations for Sentinel's flow control and circuit breaker library. It enables dynamic configuration management by allowing integration with various external configuration sources like files, databases, or configuration centers, supporting both read and write operations with automatic refresh mechanisms for real-time rule updates.
3

4
## Package Information
5

6
- **Package Name**: sentinel-datasource-extension
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven `pom.xml`:
10

11
```xml
12
<dependency>
13
    <groupId>com.alibaba.csp</groupId>
14
    <artifactId>sentinel-datasource-extension</artifactId>
15
    <version>1.8.8</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
import com.alibaba.csp.sentinel.datasource.ReadableDataSource;
23
import com.alibaba.csp.sentinel.datasource.WritableDataSource;
24
import com.alibaba.csp.sentinel.datasource.Converter;
25
import com.alibaba.csp.sentinel.datasource.AbstractDataSource;
26
import com.alibaba.csp.sentinel.datasource.FileRefreshableDataSource;
27
import com.alibaba.csp.sentinel.datasource.FileWritableDataSource;
28
```
29

30
## Basic Usage
31

32
```java
33
import com.alibaba.csp.sentinel.datasource.*;
34
import java.io.File;
35

36
// Create a converter for rule parsing
37
Converter<String, List<FlowRule>> converter = source -> {
38
    // Parse JSON/XML configuration to FlowRule objects
39
    return JSON.parseArray(source, FlowRule.class);
40
};
41

42
// File-based readable data source with auto-refresh
43
ReadableDataSource<String, List<FlowRule>> readableDs = 
44
    new FileRefreshableDataSource<>(
45
        new File("/path/to/rules.json"), 
46
        converter
47
    );
48

49
// Get the current rules
50
List<FlowRule> rules = readableDs.loadConfig();
51

52
// Access property for dynamic updates
53
SentinelProperty<List<FlowRule>> property = readableDs.getProperty();
54
property.addListener(rules -> {
55
    // Update flow rules when file changes
56
    FlowRuleManager.loadRules(rules);
57
});
58

59
// File-based writable data source
60
Converter<List<FlowRule>, String> encoder = rules -> JSON.toJSONString(rules);
61
WritableDataSource<List<FlowRule>> writableDs = 
62
    new FileWritableDataSource<>("/path/to/rules.json", encoder);
63

64
// Write updated rules
65
writableDs.write(updatedRules);
66
```
67

68
## Architecture
69

70
Sentinel DataSource Extension is built around several key components:
71

72
- **Core Interfaces**: `ReadableDataSource`, `WritableDataSource`, and `Converter` define the contracts for data source operations
73
- **Abstract Base Classes**: `AbstractDataSource` and `AutoRefreshDataSource` provide common functionality and auto-refresh capabilities
74
- **File-based Implementations**: Concrete implementations for local file systems and JAR-embedded resources
75
- **Converter Pattern**: Flexible data transformation between source formats and target types
76
- **Property System**: Integration with Sentinel's property system for dynamic rule updates
77

78
## Capabilities
79

80
### Core Interfaces
81

82
Fundamental interfaces that define the contracts for readable and writable data sources, plus the converter pattern for data transformation.
83

84
```java { .api }
85
public interface ReadableDataSource<S, T> {
86
    T loadConfig() throws Exception;
87
    S readSource() throws Exception;
88
    SentinelProperty<T> getProperty();
89
    void close() throws Exception;
90
}
91

92
public interface WritableDataSource<T> {
93
    void write(T value) throws Exception;
94
    void close() throws Exception;
95
}
96

97
public interface Converter<S, T> {
98
    T convert(S source);
99
}
100
```
101

102
[Core Interfaces](./core-interfaces.md)
103

104
### Abstract Base Classes
105

106
Base classes providing common data source functionality and automatic refresh capabilities for building custom data source implementations.
107

108
```java { .api }
109
public abstract class AbstractDataSource<S, T> implements ReadableDataSource<S, T> {
110
    public AbstractDataSource(Converter<S, T> parser);
111
    public T loadConfig() throws Exception;
112
    public T loadConfig(S conf) throws Exception;
113
    public SentinelProperty<T> getProperty();
114
}
115

116
public abstract class AutoRefreshDataSource<S, T> extends AbstractDataSource<S, T> {
117
    public AutoRefreshDataSource(Converter<S, T> configParser);
118
    public AutoRefreshDataSource(Converter<S, T> configParser, long recommendRefreshMs);
119
    public void close() throws Exception;
120
    protected boolean isModified();
121
}
122
```
123

124
[Base Classes](./base-classes.md)
125

126
### File Data Sources
127

128
Implementations for file-based data sources supporting local files, JAR-embedded resources, and automatic refresh mechanisms.
129

130
```java { .api }
131
public class FileRefreshableDataSource<T> extends AutoRefreshDataSource<String, T> {
132
    public FileRefreshableDataSource(File file, Converter<String, T> configParser) throws FileNotFoundException;
133
    public FileRefreshableDataSource(String fileName, Converter<String, T> configParser) throws FileNotFoundException;
134
    // Additional constructors with buffer size and charset options
135
}
136

137
public class FileWritableDataSource<T> implements WritableDataSource<T> {
138
    public FileWritableDataSource(String filePath, Converter<T, String> configEncoder);
139
    public FileWritableDataSource(File file, Converter<T, String> configEncoder);
140
    public void write(T value) throws Exception;
141
}
142
```
143

144
[File Data Sources](./file-datasources.md)
145

146
### Specialized Data Sources
147

148
Additional data source implementations including JAR-embedded file support and empty data sources for default configurations.
149

150
```java { .api }
151
public class FileInJarReadableDataSource<T> extends AbstractDataSource<String, T> {
152
    public FileInJarReadableDataSource(String jarName, String fileInJarName, Converter<String, T> configParser) throws IOException;
153
    public String readSource() throws Exception;
154
}
155

156
public final class EmptyDataSource implements ReadableDataSource<Object, Object> {
157
    public static final ReadableDataSource<Object, Object> EMPTY_DATASOURCE;
158
    public Object loadConfig() throws Exception;
159
    public SentinelProperty<Object> getProperty();
160
}
161
```
162

163
[Specialized Data Sources](./specialized-datasources.md)
164

165
## Types
166

167
```java { .api }
168
// External dependencies from sentinel-core
169
interface SentinelProperty<T> {
170
    void addListener(PropertyListener<T> listener);
171
    void updateValue(T newValue);
172
    T getValue();
173
}
174

175
interface PropertyListener<T> {
176
    void configUpdate(T value);
177
    void configLoad(T value);
178
}
179

180
// Common exceptions
181
class FileNotFoundException extends Exception {}
182
class IOException extends Exception {}
183
class IllegalArgumentException extends RuntimeException {}
184
class IllegalStateException extends RuntimeException {}
185
```