org.apache.flink.runtime.state.StateObject 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;
import java.io.Serializable;
/**
* Base of all handles that represent checkpointed state in some form. The object may hold the
* (small) state directly, or contain a file path (state is in the file), or contain the metadata to
* access the state stored in some external database.
*
* State objects define how to {@link #discardState() discard state} and how to access the {@link
* #getStateSize() size of the state}.
*
*
State Objects are transported via RPC between JobManager and TaskManager and
* must be {@link java.io.Serializable serializable} to support that.
*
*
Some State Objects are stored in the checkpoint/savepoint metadata. For long-term
* compatibility, they are not stored via {@link java.io.Serializable Java Serialization}, but
* through custom serializers.
*/
public interface StateObject extends Serializable {
/**
* Discards the state referred to and solemnly owned by this handle, to free up resources in the
* persistent storage. This method is called when the state represented by this object will not
* be used any more.
*/
void discardState() throws Exception;
/**
* Returns the size of the state in bytes. If the size is not known, this method should return
* {@code 0}.
*
*
The values produced by this method are only used for informational purposes and for
* metrics/monitoring. If this method returns wrong values, the checkpoints and recovery will
* still behave correctly. However, efficiency may be impacted (wrong space pre-allocation) and
* functionality that depends on metrics (like monitoring) will be impacted.
*
*
Note for implementors: This method should not perform any I/O operations while obtaining
* the state size (hence it does not declare throwing an {@code IOException}). Instead, the
* state size should be stored in the state object, or should be computable from the state
* stored in this object. The reason is that this method is called frequently by several parts
* of the checkpointing and issuing I/O requests from this method accumulates a heavy I/O load
* on the storage system at higher scale.
*
* @return Size of the state in bytes.
*/
long getStateSize();
}