org.apache.flink.runtime.state.heap.StateMap Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.flink.runtime.state.heap;
import org.apache.flink.annotation.VisibleForTesting;
import org.apache.flink.runtime.state.StateEntry;
import org.apache.flink.runtime.state.StateTransformationFunction;
import org.apache.flink.runtime.state.internal.InternalKvState;
import javax.annotation.Nonnull;
import java.util.stream.Stream;
/**
* Base class for state maps.
*
* @param type of key
* @param type of namespace
* @param type of state
*/
public abstract class StateMap implements Iterable> {
// Main interface methods of StateMap -------------------------------------------------------
/**
* Returns whether this {@link StateMap} is empty.
*
* @return {@code true} if this {@link StateMap} has no elements, {@code false}
* otherwise.
* @see #size()
*/
public boolean isEmpty() {
return size() == 0;
}
/**
* Returns the total number of entries in this {@link StateMap}.
*
* @return the number of entries in this {@link StateMap}.
*/
public abstract int size();
/**
* Returns the state for the composite of active key and given namespace.
*
* @param key the key. Not null.
* @param namespace the namespace. Not null.
* @return the state of the mapping with the specified key/namespace composite key, or {@code null}
* if no mapping for the specified key is found.
*/
public abstract S get(K key, N namespace);
/**
* Returns whether this map contains the specified key/namespace composite key.
*
* @param key the key in the composite key to search for. Not null.
* @param namespace the namespace in the composite key to search for. Not null.
* @return {@code true} if this map contains the specified key/namespace composite key,
* {@code false} otherwise.
*/
public abstract boolean containsKey(K key, N namespace);
/**
* Maps the specified key/namespace composite key to the specified value. This method should be preferred
* over {@link #putAndGetOld(K, N, S)} (Namespace, State)} when the caller is not interested in the old state.
*
* @param key the key. Not null.
* @param namespace the namespace. Not null.
* @param state the state. Can be null.
*/
public abstract void put(K key, N namespace, S state);
/**
* Maps the composite of active key and given namespace to the specified state. Returns the previous state that
* was registered under the composite key.
*
* @param key the key. Not null.
* @param namespace the namespace. Not null.
* @param state the state. Can be null.
* @return the state of any previous mapping with the specified key or
* {@code null} if there was no such mapping.
*/
public abstract S putAndGetOld(K key, N namespace, S state);
/**
* Removes the mapping for the composite of active key and given namespace. This method should be preferred
* over {@link #removeAndGetOld(K, N)} when the caller is not interested in the old state.
*
* @param key the key of the mapping to remove. Not null.
* @param namespace the namespace of the mapping to remove. Not null.
*/
public abstract void remove(K key, N namespace);
/**
* Removes the mapping for the composite of active key and given namespace, returning the state that was
* found under the entry.
*
* @param key the key of the mapping to remove. Not null.
* @param namespace the namespace of the mapping to remove. Not null.
* @return the state of the removed mapping or {@code null} if no mapping
* for the specified key was found.
*/
public abstract S removeAndGetOld(K key, N namespace);
/**
* Applies the given {@link StateTransformationFunction} to the state (1st input argument), using the given value as
* second input argument. The result of {@link StateTransformationFunction#apply(Object, Object)} is then stored as
* the new state. This function is basically an optimization for get-update-put pattern.
*
* @param key the key. Not null.
* @param namespace the namespace. Not null.
* @param value the value to use in transforming the state. Can be null.
* @param transformation the transformation function.
* @throws Exception if some exception happens in the transformation function.
*/
public abstract void transform(
K key,
N namespace,
T value,
StateTransformationFunction transformation) throws Exception;
// For queryable state ------------------------------------------------------------------------
public abstract Stream getKeys(N namespace);
public abstract InternalKvState.StateIncrementalVisitor getStateIncrementalVisitor(int recommendedMaxNumberOfReturnedRecords);
/**
* Creates a snapshot of this {@link StateMap}, to be written in checkpointing. Users should call
* {@link #releaseSnapshot(StateMapSnapshot)} after using the returned object.
*
* @return a snapshot from this {@link StateMap}, for checkpointing.
*/
@Nonnull
public abstract StateMapSnapshot> stateSnapshot();
/**
* Releases a snapshot for this {@link StateMap}. This method should be called once a snapshot is no more needed.
*
* @param snapshotToRelease the snapshot to release, which was previously created by this state map.
*/
public void releaseSnapshot(StateMapSnapshot> snapshotToRelease) {
}
// For testing --------------------------------------------------------------------------------
@VisibleForTesting
public abstract int sizeOfNamespace(Object namespace);
}