0
# State Backend Management
1

2
Core state backend system providing pluggable storage implementations, configuration management, and factory methods for creating state backends with different strategies and storage types.
3

4
## Capabilities
5

6
### State Backend Builder
7

8
Factory class for creating state backends from configuration maps, supporting automatic backend type detection and default fallback behavior.
9

10
```java { .api }
11
/**
12
 * Factory for creating state backends from configuration
13
 */
14
public class StateBackendBuilder {
15
    /**
16
     * Build state backend from configuration map
17
     * @param config Configuration map containing backend settings
18
     * @return AbstractStateBackend instance based on configuration
19
     */
20
    public static AbstractStateBackend buildStateBackend(Map<String, String> config);
21
}
22
```
23

24
**Usage Examples:**
25

26
```java
27
import io.ray.streaming.state.backend.StateBackendBuilder;
28
import java.util.Map;
29
import java.util.HashMap;
30

31
// Create with explicit configuration
32
Map<String, String> config = new HashMap<>();
33
config.put("state.backend.type", "MEMORY");
34
config.put("state.strategy.mode", "DUAL_VERSION");
35
AbstractStateBackend backend = StateBackendBuilder.buildStateBackend(config);
36

37
// Create with default configuration (uses MEMORY backend)
38
AbstractStateBackend defaultBackend = StateBackendBuilder.buildStateBackend(null);
39
```
40

41
### Abstract State Backend
42

43
Base class for all state backend implementations providing core storage operations, strategy management, and table name generation for state descriptors.
44

45
```java { .api }
46
/**
47
 * Base class for different state backends
48
 */
49
public abstract class AbstractStateBackend {
50
    /**
51
     * Get key-value store for the specified table
52
     * @param tableName Name of the table
53
     * @return KeyValueStore instance
54
     */
55
    public abstract <K, V> KeyValueStore<K, V> getKeyValueStore(String tableName);
56
    
57
    /**
58
     * Get key-map store for the specified table
59
     * @param tableName Name of the table
60
     * @return KeyMapStore instance
61
     */
62
    public abstract <K, S, T> KeyMapStore<K, S, T> getKeyMapStore(String tableName);
63
    
64
    /**
65
     * Get the backend type
66
     * @return BackendType enum value
67
     */
68
    public abstract BackendType getBackendType();
69
    
70
    /**
71
     * Get the state strategy
72
     * @return StateStrategy enum value
73
     */
74
    public abstract StateStrategy getStateStrategy();
75
    
76
    /**
77
     * Generate table name for state descriptor
78
     * @param stateDescriptor State descriptor
79
     * @return Generated table name
80
     */
81
    public String getTableName(AbstractStateDescriptor stateDescriptor);
82
    
83
    /**
84
     * Generate state key from descriptor name and current key
85
     * @param descName Descriptor name
86
     * @param currentKey Current key
87
     * @return Generated state key
88
     */
89
    public String getStateKey(String descName, String currentKey);
90
    
91
    /**
92
     * Set key group index for partitioning
93
     * @param keyGroupIndex Key group index
94
     */
95
    public void setKeyGroupIndex(int keyGroupIndex);
96
}
97
```
98

99
### Memory State Backend Implementation
100

101
Memory-based state backend implementation providing in-memory storage for both key-value and key-map stores, suitable for development and testing environments.
102

103
```java { .api }
104
/**
105
 * Memory-based state backend implementation
106
 */
107
public class MemoryStateBackend extends AbstractStateBackend {
108
    /**
109
     * Create memory state backend with configuration
110
     * @param config Configuration map
111
     */
112
    public MemoryStateBackend(Map<String, String> config);
113
    
114
    /**
115
     * Get memory-based key-value store
116
     * @param tableName Table name
117
     * @return MemoryKeyValueStore instance
118
     */
119
    public <K, V> KeyValueStore<K, V> getKeyValueStore(String tableName);
120
    
121
    /**
122
     * Get memory-based key-map store
123
     * @param tableName Table name
124
     * @return MemoryKeyMapStore instance
125
     */
126
    public <K, S, T> KeyMapStore<K, S, T> getKeyMapStore(String tableName);
127
}
128
```
129

130
### Backend Type Enumeration
131

132
Enumeration defining available backend storage types with string-based configuration support and case-insensitive parsing.
133

134
```java { .api }
135
/**
136
 * Backend storage types
137
 */
138
public enum BackendType {
139
    /** Memory-based backend for in-memory storage */
140
    MEMORY;
141
    
142
    /**
143
     * Get enum from string value, ignoring case
144
     * @param value String value to parse
145
     * @return BackendType enum, defaults to MEMORY if not found
146
     */
147
    public static BackendType getEnum(String value);
148
}
149
```
150

151
### State Strategy Enumeration
152

153
Enumeration defining state saving strategies for different consistency and performance requirements.
154

155
```java { .api }
156
/**
157
 * State saving strategies
158
 */
159
public enum StateStrategy {
160
    /** Save two versions for rollback support */
161
    DUAL_VERSION,
162
    /** Save only current version for MVCC storage */
163
    SINGLE_VERSION;
164
    
165
    /**
166
     * Get enum from string value, ignoring case
167
     * @param value String value to parse
168
     * @return StateStrategy enum, defaults to DUAL_VERSION if not found
169
     */
170
    public static StateStrategy getEnum(String value);
171
}
172
```
173

174
**Usage Examples:**
175

176
```java
177
// Backend type configuration
178
BackendType type = BackendType.getEnum("memory"); // MEMORY
179
BackendType defaultType = BackendType.getEnum("invalid"); // MEMORY (default)
180

181
// Strategy configuration
182
StateStrategy strategy = StateStrategy.getEnum("DUAL_VERSION"); // DUAL_VERSION
183
StateStrategy mvccStrategy = StateStrategy.getEnum("single_version"); // SINGLE_VERSION
184
```
185

186
### Operator State Backend
187

188
Specialized state backend for operator-level state management supporting split and union list states for parallel processing patterns.
189

190
```java { .api }
191
/**
192
 * Operator state manager for split or union list states
193
 */
194
public class OperatorStateBackend {
195
    /**
196
     * Create operator state backend
197
     * @param backend Underlying state backend
198
     */
199
    public OperatorStateBackend(AbstractStateBackend backend);
200
    
201
    /**
202
     * Set current processing key
203
     * @param currentKey Current key
204
     */
205
    public void setCurrentKey(Object currentKey);
206
    
207
    /**
208
     * Get split list state for parallel processing
209
     * @param stateDescriptor List state descriptor
210
     * @return ListState instance for split operations
211
     */
212
    public <T> ListState<T> getSplitListState(ListStateDescriptor<T> stateDescriptor);
213
    
214
    /**
215
     * Get union list state for aggregated processing
216
     * @param stateDescriptor List state descriptor
217
     * @return ListState instance for union operations
218
     */
219
    public <T> ListState<T> getUnionListState(ListStateDescriptor<T> stateDescriptor);
220
}
221
```
222

223
**Usage Examples:**
224

225
```java
226
// Create operator state backend
227
AbstractStateBackend backend = StateBackendBuilder.buildStateBackend(config);
228
OperatorStateBackend operatorBackend = new OperatorStateBackend(backend);
229

230
// Create split list state for parallel processing
231
ListStateDescriptor<String> splitDesc = ListStateDescriptor.build("split-state", String.class, true);
232
ListState<String> splitState = operatorBackend.getSplitListState(splitDesc);
233

234
// Create union list state for aggregation
235
ListStateDescriptor<Integer> unionDesc = ListStateDescriptor.build("union-state", Integer.class, true);
236
ListState<Integer> unionState = operatorBackend.getUnionListState(unionDesc);
237
```