0
# Apache Flink Queryable State Client Java
1

2
**⚠️ DEPRECATED**: This feature is deprecated since Flink 1.18 and will be removed in a future major version.
3

4
Apache Flink Queryable State Client Java is a client library that enables external applications to query the state of running Apache Flink streaming jobs through a network-based interface. The library provides programmatic access to various types of keyed state including ValueState, ListState, MapState, AggregatingState, and ReducingState from Flink applications that have enabled queryable state.
5

6
## Package Information
7

8
- **Package Name**: flink-queryable-state-client-java
9
- **Package Type**: Maven
10
- **Language**: Java
11
- **Installation**: 
12
  ```xml
13
  <dependency>
14
    <groupId>org.apache.flink</groupId>
15
    <artifactId>flink-queryable-state-client-java</artifactId>
16
    <version>2.1.0</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java
23
import org.apache.flink.queryablestate.client.QueryableStateClient;
24
import org.apache.flink.api.common.JobID;
25
import org.apache.flink.api.common.state.*;
26
import org.apache.flink.api.common.typeinfo.TypeInformation;
27
import org.apache.flink.api.common.typeinfo.TypeHint;
28
import org.apache.flink.queryablestate.client.VoidNamespace;
29
import org.apache.flink.queryablestate.client.VoidNamespaceTypeInfo;
30
import org.apache.flink.queryablestate.client.VoidNamespaceSerializer;
31
import org.apache.flink.queryablestate.KvStateID;
32
```
33

34
## Basic Usage
35

36
```java
37
import org.apache.flink.queryablestate.client.QueryableStateClient;
38
import org.apache.flink.api.common.JobID;
39
import org.apache.flink.api.common.state.ValueState;
40
import org.apache.flink.api.common.state.ValueStateDescriptor;
41
import org.apache.flink.api.common.typeinfo.TypeInformation;
42
import java.util.concurrent.CompletableFuture;
43

44
// Create client
45
QueryableStateClient client = new QueryableStateClient("localhost", 9069);
46

47
// Configure execution config (optional)
48
ExecutionConfig config = new ExecutionConfig();
49
client.setExecutionConfig(config);
50

51
// Query state
52
JobID jobId = JobID.fromHexString("your-job-id-here");
53
String stateName = "myQueryableState";
54
String key = "someKey";
55
ValueStateDescriptor<String> descriptor = new ValueStateDescriptor<>("state", String.class);
56

57
CompletableFuture<ValueState<String>> future = client.getKvState(
58
    jobId, 
59
    stateName, 
60
    key, 
61
    TypeInformation.of(String.class), 
62
    descriptor
63
);
64

65
// Handle result
66
future.thenAccept(state -> {
67
    String value = state.value();
68
    System.out.println("State value: " + value);
69
}).exceptionally(throwable -> {
70
    System.err.println("Query failed: " + throwable.getMessage());
71
    return null;
72
});
73

74
// Shutdown client
75
client.shutdownAndWait();
76
```
77

78
## Architecture
79

80
The queryable state client follows a multi-tier architecture:
81

82
- **QueryableStateClient**: Main entry point providing type-safe, asynchronous state querying
83
- **Network Layer**: Netty-based communication with Flink cluster via client proxy
84
- **Immutable State Wrappers**: Read-only state objects (ImmutableValueState, ImmutableListState, etc.)
85
- **Message Protocol**: Structured request/response messaging with serialized state data
86
- **Location Resolution**: Caching system for resolved state locations via JobManager communication
87

88
The client resolves state locations through JobManager communication, caches resolved locations for performance, and provides a type-safe API for accessing state with proper serialization support.
89

90
## Capabilities
91

92
### Client Management
93

94
Core client functionality for connecting to Flink clusters, managing configuration, and lifecycle operations.
95

96
```java { .api }
97
public class QueryableStateClient {
98
    public QueryableStateClient(String remoteHostname, int remotePort) throws UnknownHostException;
99
    public QueryableStateClient(InetAddress remoteAddress, int remotePort);
100
    
101
    public ExecutionConfig getExecutionConfig();
102
    public ExecutionConfig setExecutionConfig(ExecutionConfig config);
103
    public ClassLoader setUserClassLoader(ClassLoader userClassLoader);
104
    
105
    public CompletableFuture<?> shutdownAndHandle();
106
    public void shutdownAndWait();
107
}
108
```
109

110
[Client Management](./client-management.md)
111

112
### State Querying
113

114
Asynchronous state querying capabilities for accessing different types of keyed state from running Flink jobs.
115

116
```java { .api }
117
public <K, S extends State, V> CompletableFuture<S> getKvState(
118
    JobID jobId,
119
    String queryableStateName,
120
    K key,
121
    TypeHint<K> keyTypeHint,
122
    StateDescriptor<S, V> stateDescriptor
123
);
124

125
public <K, S extends State, V> CompletableFuture<S> getKvState(
126
    JobID jobId,
127
    String queryableStateName,
128
    K key,
129
    TypeInformation<K> keyTypeInfo,
130
    StateDescriptor<S, V> stateDescriptor
131
);
132
```
133

134
[State Querying](./state-querying.md)
135

136
### Immutable State Types
137

138
Read-only state wrappers returned from queries, providing access to state values while preventing modifications.
139

140
```java { .api }
141
public final class ImmutableValueState<V> implements ValueState<V> {
142
    public V value();
143
}
144

145
public final class ImmutableListState<V> implements ListState<V> {
146
    public Iterable<V> get();
147
}
148

149
public final class ImmutableMapState<K, V> implements MapState<K, V> {
150
    public V get(K key);
151
    public boolean contains(K key);
152
    public Iterable<Map.Entry<K, V>> entries();
153
}
154
```
155

156
[Immutable State Types](./immutable-state.md)
157

158
### Exception Handling
159

160
Comprehensive exception handling for various failure scenarios in state querying operations.
161

162
```java { .api }
163
public class UnknownKeyOrNamespaceException extends BadRequestException;
164
public class UnknownKvStateIdException extends BadRequestException;
165
public class UnknownLocationException extends FlinkException;
166
public class UnknownKvStateKeyGroupLocationException extends BadRequestException;
167
```
168

169
[Exception Handling](./exception-handling.md)
170

171
## Types
172

173
```java { .api }
174
public class KvStateID extends AbstractID {
175
    public KvStateID();
176
    public KvStateID(long lowerPart, long upperPart);
177
}
178

179
public class VoidNamespace {
180
    public static final VoidNamespace INSTANCE;
181
    public static VoidNamespace get();
182
}
183

184
public class VoidNamespaceTypeInfo extends TypeInformation<VoidNamespace> {
185
    public static final VoidNamespaceTypeInfo INSTANCE;
186
    public TypeSerializer<VoidNamespace> createSerializer(SerializerConfig config);
187
}
188

189
public class VoidNamespaceSerializer extends TypeSerializerSingleton<VoidNamespace> {
190
    public static final VoidNamespaceSerializer INSTANCE;
191
    public boolean isImmutableType();
192
    public VoidNamespace createInstance();
193
    public VoidNamespace copy(VoidNamespace from);
194
    public int getLength();
195
    public void serialize(VoidNamespace record, DataOutputView target);
196
    public VoidNamespace deserialize(DataInputView source);
197
}
198
```