or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-management.mdexception-handling.mdimmutable-state.mdindex.mdstate-querying.md
tile.json

tessl/maven-org-apache-flink--flink-queryable-state-client-java

Java client library for accessing queryable state in Apache Flink streaming applications through a network-based query interface.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.apache.flink/flink-queryable-state-client-java@2.1.x

To install, run

npx @tessl/cli install tessl/maven-org-apache-flink--flink-queryable-state-client-java@2.1.0

index.mddocs/

Apache Flink Queryable State Client Java

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

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.

Package Information

  • Package Name: flink-queryable-state-client-java
  • Package Type: Maven
  • Language: Java
  • Installation: 
    <dependency>
  <groupId>org.apache.flink</groupId>
  <artifactId>flink-queryable-state-client-java</artifactId>
  <version>2.1.0</version>
</dependency>

Core Imports

import org.apache.flink.queryablestate.client.QueryableStateClient;
import org.apache.flink.api.common.JobID;
import org.apache.flink.api.common.state.*;
import org.apache.flink.api.common.typeinfo.TypeInformation;
import org.apache.flink.api.common.typeinfo.TypeHint;
import org.apache.flink.queryablestate.client.VoidNamespace;
import org.apache.flink.queryablestate.client.VoidNamespaceTypeInfo;
import org.apache.flink.queryablestate.client.VoidNamespaceSerializer;
import org.apache.flink.queryablestate.KvStateID;

Basic Usage

import org.apache.flink.queryablestate.client.QueryableStateClient;
import org.apache.flink.api.common.JobID;
import org.apache.flink.api.common.state.ValueState;
import org.apache.flink.api.common.state.ValueStateDescriptor;
import org.apache.flink.api.common.typeinfo.TypeInformation;
import java.util.concurrent.CompletableFuture;

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

// Configure execution config (optional)
ExecutionConfig config = new ExecutionConfig();
client.setExecutionConfig(config);

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

CompletableFuture<ValueState<String>> future = client.getKvState(
    jobId, 
    stateName, 
    key, 
    TypeInformation.of(String.class), 
    descriptor
);

// Handle result
future.thenAccept(state -> {
    String value = state.value();
    System.out.println("State value: " + value);
}).exceptionally(throwable -> {
    System.err.println("Query failed: " + throwable.getMessage());
    return null;
});

// Shutdown client
client.shutdownAndWait();

Architecture

The queryable state client follows a multi-tier architecture:

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

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.

Capabilities

Client Management

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

public class QueryableStateClient {
    public QueryableStateClient(String remoteHostname, int remotePort) throws UnknownHostException;
    public QueryableStateClient(InetAddress remoteAddress, int remotePort);
    
    public ExecutionConfig getExecutionConfig();
    public ExecutionConfig setExecutionConfig(ExecutionConfig config);
    public ClassLoader setUserClassLoader(ClassLoader userClassLoader);
    
    public CompletableFuture<?> shutdownAndHandle();
    public void shutdownAndWait();
}

Client Management

State Querying

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

public <K, S extends State, V> CompletableFuture<S> getKvState(
    JobID jobId,
    String queryableStateName,
    K key,
    TypeHint<K> keyTypeHint,
    StateDescriptor<S, V> stateDescriptor
);

public <K, S extends State, V> CompletableFuture<S> getKvState(
    JobID jobId,
    String queryableStateName,
    K key,
    TypeInformation<K> keyTypeInfo,
    StateDescriptor<S, V> stateDescriptor
);

State Querying

Immutable State Types

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

public final class ImmutableValueState<V> implements ValueState<V> {
    public V value();
}

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

public final class ImmutableMapState<K, V> implements MapState<K, V> {
    public V get(K key);
    public boolean contains(K key);
    public Iterable<Map.Entry<K, V>> entries();
}

Immutable State Types

Exception Handling

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

public class UnknownKeyOrNamespaceException extends BadRequestException;
public class UnknownKvStateIdException extends BadRequestException;
public class UnknownLocationException extends FlinkException;
public class UnknownKvStateKeyGroupLocationException extends BadRequestException;

Exception Handling

Types

public class KvStateID extends AbstractID {
    public KvStateID();
    public KvStateID(long lowerPart, long upperPart);
}

public class VoidNamespace {
    public static final VoidNamespace INSTANCE;
    public static VoidNamespace get();
}

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

public class VoidNamespaceSerializer extends TypeSerializerSingleton<VoidNamespace> {
    public static final VoidNamespaceSerializer INSTANCE;
    public boolean isImmutableType();
    public VoidNamespace createInstance();
    public VoidNamespace copy(VoidNamespace from);
    public int getLength();
    public void serialize(VoidNamespace record, DataOutputView target);
    public VoidNamespace deserialize(DataInputView source);
}