CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

—

Pending
Overview
Eval results
Files

immutable-state.mddocs/

Immutable State Types

Read-only state wrappers returned from queries that provide access to state values while preventing modifications. All state objects returned by the queryable state client are immutable - any attempt to modify them will throw UnsupportedOperationException.

Capabilities

ImmutableValueState

Read-only wrapper for ValueState that contains a single value.

public final class ImmutableValueState<V> implements ValueState<V> {
    public V value();
    public void update(V newValue); // Throws UnsupportedOperationException
    public void clear(); // Throws UnsupportedOperationException
}

Methods:

  • value() - Returns the stored value (never null)
  • update(V) - Always throws UnsupportedOperationException
  • clear() - Always throws UnsupportedOperationException

Usage Example:

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

future.thenAccept(state -> {
    String value = state.value(); // OK - read access
    System.out.println("Value: " + value);
    
    // state.update("new value"); // Would throw UnsupportedOperationException
    // state.clear(); // Would throw UnsupportedOperationException
});

ImmutableListState

Read-only wrapper for ListState that contains a list of values.

public final class ImmutableListState<V> implements ListState<V> {
    public Iterable<V> get();
    public void add(V value); // Throws UnsupportedOperationException
    public void update(List<V> values); // Throws UnsupportedOperationException
    public void addAll(List<V> values); // Throws UnsupportedOperationException
    public void clear(); // Throws UnsupportedOperationException
}

Methods:

  • get() - Returns an Iterable over the list values (read-only)
  • All modification methods throw UnsupportedOperationException

Usage Example:

CompletableFuture<ListState<Integer>> future = client.getKvState(
    jobId, stateName, key, TypeInformation.of(String.class),
    new ListStateDescriptor<>("numbers", Integer.class)
);

future.thenAccept(state -> {
    Iterable<Integer> values = state.get(); // OK - read access
    for (Integer value : values) {
        System.out.println("Value: " + value);
    }
    
    // state.add(42); // Would throw UnsupportedOperationException
    // state.clear(); // Would throw UnsupportedOperationException
});

ImmutableMapState

Read-only wrapper for MapState that contains key-value mappings.

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();
    public Iterable<K> keys();
    public Iterable<V> values();
    public Iterator<Map.Entry<K, V>> iterator();
    public boolean isEmpty();
    
    public void put(K key, V value); // Throws UnsupportedOperationException
    public void putAll(Map<K, V> map); // Throws UnsupportedOperationException
    public void remove(K key); // Throws UnsupportedOperationException
    public void clear(); // Throws UnsupportedOperationException
}

Read Methods:

  • get(K key) - Returns the value for the given key, or null if not present
  • contains(K key) - Returns true if the key exists in the map
  • entries() - Returns an Iterable over all key-value pairs (read-only)
  • keys() - Returns an Iterable over all keys (read-only)
  • values() - Returns an Iterable over all values (read-only)
  • iterator() - Returns a read-only Iterator over all entries
  • isEmpty() - Returns true if the map contains no entries

Usage Example:

CompletableFuture<MapState<String, Long>> future = client.getKvState(
    jobId, stateName, key, TypeInformation.of(String.class),
    new MapStateDescriptor<>("counters", String.class, Long.class)
);

future.thenAccept(state -> {
    // Read operations - all OK
    Long count = state.get("clicks");
    boolean hasClicks = state.contains("clicks");
    
    if (!state.isEmpty()) {
        for (Map.Entry<String, Long> entry : state.entries()) {
            System.out.println(entry.getKey() + ": " + entry.getValue());
        }
    }
    
    // state.put("new", 100L); // Would throw UnsupportedOperationException
    // state.remove("clicks"); // Would throw UnsupportedOperationException
});

ImmutableReducingState

Read-only wrapper for ReducingState that contains a reduced value.

public final class ImmutableReducingState<V> implements ReducingState<V> {
    public V get();
    public void add(V newValue); // Throws UnsupportedOperationException
    public void clear(); // Throws UnsupportedOperationException
}

Methods:

  • get() - Returns the reduced value, or null if no values were added
  • All modification methods throw UnsupportedOperationException

Usage Example:

CompletableFuture<ReducingState<Integer>> future = client.getKvState(
    jobId, stateName, key, TypeInformation.of(String.class),
    new ReducingStateDescriptor<>("sum", Integer::sum, Integer.class)
);

future.thenAccept(state -> {
    Integer sum = state.get(); // OK - read access
    System.out.println("Sum: " + sum);
    
    // state.add(10); // Would throw UnsupportedOperationException
});

ImmutableAggregatingState

Read-only wrapper for AggregatingState that contains an aggregated result.

public final class ImmutableAggregatingState<IN, OUT> implements AggregatingState<IN, OUT> {
    public OUT get();
    public void add(Object newValue); // Throws UnsupportedOperationException
    public void clear(); // Throws UnsupportedOperationException
}

Methods:

  • get() - Returns the aggregated result, or null if no values were aggregated
  • All modification methods throw UnsupportedOperationException

Usage Example:

// Assuming an AggregateFunction that takes Integer input and produces Double output
CompletableFuture<AggregatingState<Integer, Double>> future = client.getKvState(
    jobId, stateName, key, TypeInformation.of(String.class),
    new AggregatingStateDescriptor<>("average", avgFunction, Double.class)
);

future.thenAccept(state -> {
    Double average = state.get(); // OK - read access
    System.out.println("Average: " + average);
    
    // state.add(5); // Would throw UnsupportedOperationException
});

Immutability Enforcement

All immutable state classes extend the abstract ImmutableState class, which provides:

public abstract class ImmutableState {
    protected static final UnsupportedOperationException MODIFICATION_ATTEMPT_ERROR;
}

This shared constant is thrown by all modification methods to provide consistent error messages when attempting to modify read-only state.

State Creation

Immutable state objects are created internally by the QueryableStateClient using factory methods:

// Factory methods (internal usage)
public static <V, S extends State> S createState(
    StateDescriptor<S, V> stateDescriptor, 
    byte[] serializedState
) throws Exception;

These factory methods deserialize the state data received from the Flink cluster and wrap it in the appropriate immutable state implementation.

Thread Safety

All immutable state objects are thread-safe for read operations since they cannot be modified after creation. Multiple threads can safely call read methods (like value(), get(), entries(), etc.) concurrently without synchronization.

Install with Tessl CLI

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

docs

client-management.md

exception-handling.md

immutable-state.md

index.md

state-querying.md

tile.json