0
# State Types and Operations
1

2
Three core state abstractions - ValueState for single values, ListState for ordered collections, and MapState for key-value mappings - each providing specialized operations and transaction support for different data access patterns.
3

4
## Capabilities
5

6
### Base State Interface
7

8
Root interface for all state types providing common functionality for key management.
9

10
```java { .api }
11
/**
12
 * Base interface for all state types
13
 */
14
public interface State {
15
    /**
16
     * Set current key for state operations
17
     * @param currentKey Current processing key
18
     */
19
    void setCurrentKey(Object currentKey);
20
}
21
```
22

23
### Unary State Interface
24

25
Interface for states that contain a single value, providing base functionality for value retrieval.
26

27
```java { .api }
28
/**
29
 * Interface for single-value states
30
 */
31
public interface UnaryState<O> extends State {
32
    /**
33
     * Get the current value stored in state
34
     * @return Current value or null if not set
35
     */
36
    O get();
37
}
38
```
39

40
### Value State
41

42
State type for storing and managing single values with update capabilities and default value support.
43

44
```java { .api }
45
/**
46
 * Value state for storing single values
47
 */
48
public interface ValueState<T> extends UnaryState<T> {
49
    /**
50
     * Update the stored value
51
     * @param value New value to store
52
     */
53
    void update(T value);
54
}
55
```
56

57
**Usage Examples:**
58

59
```java
60
// Create value state for user session information
61
ValueStateDescriptor<String> sessionDesc = ValueStateDescriptor.build("user-session", String.class, "");
62
ValueState<String> sessionState = keyStateBackend.getValueState(sessionDesc);
63

64
// Set current key and use state
65
keyStateBackend.setCurrentKey("user123");
66

67
// Update and retrieve values
68
sessionState.update("session-abc-123");
69
String currentSession = sessionState.get(); // "session-abc-123"
70

71
// Check if value exists (null if not set, default value if specified)
72
keyStateBackend.setCurrentKey("new-user");
73
String newUserSession = sessionState.get(); // "" (default value)
74
```
75

76
### List State
77

78
State type for storing and managing ordered collections with add and update operations for list-based data patterns.
79

80
```java { .api }
81
/**
82
 * List state for storing ordered collections
83
 */
84
public interface ListState<T> extends UnaryState<List<T>> {
85
    /**
86
     * Add a single value to the end of the list
87
     * @param value Value to add
88
     */
89
    void add(T value);
90
    
91
    /**
92
     * Replace the entire list with new values
93
     * @param list New list to store
94
     */
95
    void update(List<T> list);
96
}
97
```
98

99
**Usage Examples:**
100

101
```java
102
import java.util.List;
103
import java.util.ArrayList;
104

105
// Create list state for user events
106
ListStateDescriptor<String> eventsDesc = ListStateDescriptor.build("user-events", String.class);
107
ListState<String> eventsState = keyStateBackend.getListState(eventsDesc);
108

109
// Set current key
110
keyStateBackend.setCurrentKey("user123");
111

112
// Add individual events
113
eventsState.add("login");
114
eventsState.add("page-view:/home");
115
eventsState.add("click:button-submit");
116

117
// Get current list
118
List<String> currentEvents = eventsState.get();
119
// Result: ["login", "page-view:/home", "click:button-submit"]
120

121
// Replace entire list
122
List<String> newEvents = new ArrayList<>();
123
newEvents.add("logout");
124
eventsState.update(newEvents);
125

126
List<String> updatedEvents = eventsState.get();
127
// Result: ["logout"]
128
```
129

130
### Map State
131

132
State type for storing and managing key-value mappings with comprehensive map operations including get, put, remove, and bulk operations.
133

134
```java
135
import java.util.Iterator;
136
import java.util.Map;
137
import java.util.Map.Entry;
138
```
139

140
```java { .api }
141
/**
142
 * Map state for storing key-value mappings
143
 */
144
public interface MapState<K, V> extends UnaryState<Map<K, V>> {
145
    /**
146
     * Get value associated with the specified key
147
     * @param key Key to look up
148
     * @return Value associated with key, or null if not found
149
     */
150
    V get(K key);
151
    
152
    /**
153
     * Associate a value with the specified key
154
     * @param key Key to store
155
     * @param value Value to associate with key
156
     */
157
    void put(K key, V value);
158
    
159
    /**
160
     * Replace the entire map with new mappings
161
     * @param map New map to store
162
     */
163
    void update(Map<K, V> map);
164
    
165
    /**
166
     * Copy all mappings from the provided map into state
167
     * @param map Map containing mappings to add
168
     */
169
    void putAll(Map<K, V> map);
170
    
171
    /**
172
     * Remove mapping for the specified key
173
     * @param key Key to remove
174
     */
175
    void remove(K key);
176
    
177
    /**
178
     * Check if mapping exists for the specified key
179
     * @param key Key to check
180
     * @return True if key exists in map
181
     */
182
    default boolean contains(K key) {
183
        return get().containsKey(key);
184
    }
185
    
186
    /**
187
     * Get all key-value entries in the map
188
     * @return Iterable view of all entries
189
     */
190
    default Iterable<Entry<K, V>> entries() {
191
        return get().entrySet();
192
    }
193
    
194
    /**
195
     * Get all keys in the map
196
     * @return Iterable view of all keys
197
     */
198
    default Iterable<K> keys() {
199
        return get().keySet();
200
    }
201
    
202
    /**
203
     * Get all values in the map
204
     * @return Iterable view of all values
205
     */
206
    default Iterable<V> values() {
207
        return get().values();
208
    }
209
    
210
    /**
211
     * Get iterator over all key-value entries
212
     * @return Iterator over all entries
213
     */
214
    default Iterator<Entry<K, V>> iterator() {
215
        return get().entrySet().iterator();
216
    }
217
}
218
```
219

220
**Usage Examples:**
221

222
```java
223
import java.util.Map;
224
import java.util.HashMap;
225
import java.util.Iterator;
226
import java.util.Map.Entry;
227

228
// Create map state for user counters
229
MapStateDescriptor<String, Integer> countersDesc = MapStateDescriptor.build("user-counters", String.class, Integer.class);
230
MapState<String, Integer> countersState = keyStateBackend.getMapState(countersDesc);
231

232
// Set current key
233
keyStateBackend.setCurrentKey("user123");
234

235
// Add individual mappings
236
countersState.put("clicks", 5);
237
countersState.put("views", 12);
238
countersState.put("purchases", 2);
239

240
// Get individual values
241
Integer clicks = countersState.get("clicks"); // 5
242
Integer views = countersState.get("views");   // 12
243

244
// Check if key exists
245
boolean hasClicks = countersState.contains("clicks"); // true
246
boolean hasDownloads = countersState.contains("downloads"); // false
247

248
// Add multiple mappings at once
249
Map<String, Integer> additionalCounters = new HashMap<>();
250
additionalCounters.put("downloads", 3);
251
additionalCounters.put("shares", 1);
252
countersState.putAll(additionalCounters);
253

254
// Remove specific mapping
255
countersState.remove("views");
256

257
// Iterate over all entries
258
for (Map.Entry<String, Integer> entry : countersState.entries()) {
259
    System.out.println(entry.getKey() + ": " + entry.getValue());
260
}
261

262
// Get all keys and values
263
Iterable<String> allKeys = countersState.keys();
264
Iterable<Integer> allValues = countersState.values();
265

266
// Replace entire map
267
Map<String, Integer> newCounters = new HashMap<>();
268
newCounters.put("new-metric", 100);
269
countersState.update(newCounters);
270

271
// Get entire map
272
Map<String, Integer> currentMap = countersState.get();
273
```
274

275
### State Implementation Classes
276

277
The library provides default implementations for all state interfaces, managed internally by the key state backend system.
278

279
#### Value State Implementation
280

281
```java { .api }
282
/**
283
 * Default implementation of ValueState interface
284
 */
285
public class ValueStateImpl<T> implements ValueState<T> {
286
    // Implementation managed by KeyStateBackend
287
}
288
```
289

290
#### List State Implementation
291

292
```java { .api }
293
/**
294
 * Default implementation of ListState interface
295
 */
296
public class ListStateImpl<T> implements ListState<T> {
297
    // Implementation managed by KeyStateBackend
298
}
299
```
300

301
#### Map State Implementation
302

303
```java { .api }
304
/**
305
 * Default implementation of MapState interface
306
 */
307
public class MapStateImpl<K, V> implements MapState<K, V> {
308
    // Implementation managed by KeyStateBackend
309
}
310
```
311

312
#### Operator State Implementation
313

314
```java { .api }
315
/**
316
 * Implementation for operator-level state
317
 */
318
public class OperatorStateImpl<T> implements ListState<T> {
319
    // Implementation managed by OperatorStateBackend
320
}
321
```
322

323
### State Helper Utilities
324

325
Utility class providing helper methods for state operations and common patterns.
326

327
```java { .api }
328
/**
329
 * Helper utilities for state operations
330
 */
331
public class StateHelper {
332
    // Various utility methods for state management
333
}
334
```
335

336
**Advanced Usage Patterns:**
337

338
```java
339
// Pattern 1: Counter with automatic initialization
340
MapState<String, Integer> counters = keyStateBackend.getMapState(countersDesc);
341
keyStateBackend.setCurrentKey("user456");
342

343
// Increment counter with null-safe operation
344
String metric = "page-views";
345
Integer currentCount = counters.get(metric);
346
counters.put(metric, (currentCount == null) ? 1 : currentCount + 1);
347

348
// Pattern 2: List state for sliding window
349
ListState<Long> timestamps = keyStateBackend.getListState(timestampDesc);
350
keyStateBackend.setCurrentKey("sensor1");
351

352
// Add new timestamp and maintain window size
353
timestamps.add(System.currentTimeMillis());
354
List<Long> allTimestamps = timestamps.get();
355
if (allTimestamps.size() > 100) {
356
    // Keep only last 100 timestamps
357
    List<Long> recentTimestamps = allTimestamps.subList(allTimestamps.size() - 100, allTimestamps.size());
358
    timestamps.update(recentTimestamps);
359
}
360

361
// Pattern 3: Value state with complex objects
362
class UserProfile {
363
    public String name;
364
    public int age;
365
    public List<String> interests;
366
}
367

368
ValueStateDescriptor<UserProfile> profileDesc = ValueStateDescriptor.build("user-profile", UserProfile.class, null);
369
ValueState<UserProfile> profileState = keyStateBackend.getValueState(profileDesc);
370

371
keyStateBackend.setCurrentKey("user789");
372
UserProfile profile = new UserProfile();
373
profile.name = "Alice";
374
profile.age = 30;
375
profile.interests = Arrays.asList("technology", "music");
376
profileState.update(profile);
377
```