com.twitter.heron.spi.statemgr.IStateManager Maven / Gradle / Ivy
// Copyright 2016 Twitter. All rights reserved.
//
// Licensed 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 com.twitter.heron.spi.statemgr;
import com.google.common.util.concurrent.ListenableFuture;
import com.twitter.heron.api.generated.TopologyAPI;
import com.twitter.heron.classification.InterfaceAudience;
import com.twitter.heron.classification.InterfaceStability;
import com.twitter.heron.proto.ckptmgr.CheckpointManager;
import com.twitter.heron.proto.scheduler.Scheduler;
import com.twitter.heron.proto.system.ExecutionEnvironment;
import com.twitter.heron.proto.system.PackingPlans;
import com.twitter.heron.proto.system.PhysicalPlans;
import com.twitter.heron.proto.tmaster.TopologyMaster;
import com.twitter.heron.spi.common.Config;
/**
* This file defines the IStateManager interface.
*
* Services across Heron use HeronStateMgr to get/set state information.
* Currently the primary things kept by state are:
* 1. Where is the the topology master running.
* The topology master is responsible for writing this information out
* upon startup. The stream managers query this upon startup to find out
* who is their topology master. In case they loose connection with
* the topology master, the stream managers query this again to see
* if the topology master has changed.
*
* 2. Topology and the current running state of the topology
* This information is seeded by the topology submitter.
* The topology master updates this when the state of the topology
* changes.
*
* 3. Current assignment.
* This information is solely used by topology master. When it
* creates a new assignment or when the assignment changes, it writes
* out this information. This is required for topology master failover.
*
* Clients call the methods of the state passing a callback. The callback
* is called with result code upon the completion of the operation.
*/
@InterfaceAudience.LimitedPrivate
@InterfaceStability.Unstable
public interface IStateManager extends AutoCloseable {
enum LockName {
UPDATE_TOPOLOGY("updateTopology");
private String name;
LockName(String name) {
this.name = name;
}
public String getName() {
return name;
}
}
/**
* Initialize StateManager with the incoming context.
*/
void initialize(Config config);
/**
* This is to for disposing or cleaning up any internal state accumulated by
* the StateManager
*
* Closes this stream and releases any system resources associated
* with it. If the stream is already closed then invoking this
* method has no effect.
*/
void close();
/**
* Is the given topology in RUNNING state?
*
* @return Boolean
*/
ListenableFuture isTopologyRunning(String topologyName);
/**
* Return a lock object backed by the state manager store.
*
* @param topologyName the name of the topology
* @param lockName any thread may get the {@code Lock} object bound to a given name, but only one
* thread may obtain the actual lock from that @{code Lock} object.
* @return an object representing an implementation of a lock.
*/
Lock getLock(String topologyName, LockName lockName);
/**
* Delete all locks for a given topology. Ideally locks should be deleted when released but it's
* possible that some state systems (e.g., ZooKeeper) will not delete all resources when a lock is
* released. This method should be invoked to clean all such lock resources.
*
* @return Boolean - Success or Failure
*/
ListenableFuture deleteLocks(String topologyName);
/**
* Set the location of Tmaster.
*
* @return Boolean - Success or Failure
*/
ListenableFuture setTMasterLocation(
TopologyMaster.TMasterLocation location, String topologyName);
/**
* Get the tmaster location for the given topology
*
* @param watcher @see com.twitter.heron.spi.statemgr.WatchCallback
* @return TMasterLocation
*/
ListenableFuture getTMasterLocation(
WatchCallback watcher, String topologyName);
/**
* Delete the tmaster location for the given topology
*
* @return Boolean - Success or Failure
*/
ListenableFuture deleteTMasterLocation(String topologyName);
/**
* Set the location of MetricsCache.
*
* @return Boolean - Success or Failure
*/
ListenableFuture setMetricsCacheLocation(
TopologyMaster.MetricsCacheLocation location, String topologyName);
/**
* Get the MetricsCache location for the given topology
*
* @param watcher @see com.twitter.heron.spi.statemgr.WatchCallback
* @return TMasterLocation
*/
ListenableFuture getMetricsCacheLocation(
WatchCallback watcher, String topologyName);
/**
* Delete the metricscache location for the given topology
*
* @return Boolean - Success or Failure
*/
ListenableFuture deleteMetricsCacheLocation(String topologyName);
/**
* Set the topology definition for the given topology
*
* @return Boolean - Success or Failure
*/
ListenableFuture setTopology(
TopologyAPI.Topology topology, String topologyName);
/**
* Get the topology definition for the given topology
*
* @param watcher @see com.twitter.heron.spi.statemgr.WatchCallback
* @return Topology
*/
ListenableFuture getTopology(
WatchCallback watcher, String topologyName);
/**
* Delete the topology definition for the given topology
*
* @return Boolean - Success or Failure
*/
ListenableFuture deleteTopology(String topologyName);
/**
* Set the packing plan for the given topology
*
* @return Boolean - Success or Failure
*/
ListenableFuture setPackingPlan(
PackingPlans.PackingPlan packingPlan, String topologyName);
/**
* Get the packing plan for the given topology
*
* @param watcher @see com.twitter.heron.spi.statemgr.WatchCallback
* @return PackingPlan
*/
ListenableFuture getPackingPlan(
WatchCallback watcher, String topologyName);
/**
* Delete the packing plan for the given topology
*
* @return Boolean - Success or Failure
*/
ListenableFuture deletePackingPlan(String topologyName);
/**
* Set the physical plan for the given topology
*
* @return Boolean - Success or Failure
*/
ListenableFuture setPhysicalPlan(
PhysicalPlans.PhysicalPlan physicalPlan, String topologyName);
/**
* Get the physical plan for the given topology
*
* @param watcher @see com.twitter.heron.spi.statemgr.WatchCallback
* @return PhysicalPlan
*/
ListenableFuture getPhysicalPlan(
WatchCallback watcher, String topologyName);
/**
* Delete the physical plan for the given topology
*
* @return Boolean - Success or Failure
*/
ListenableFuture deletePhysicalPlan(String topologyName);
/**
* Set the execution state for the given topology
*
* @return Boolean - Success or Failure
*/
ListenableFuture setExecutionState(
ExecutionEnvironment.ExecutionState executionState, String topologyName);
/**
* Get the execution state for the given topology
*
* @param watcher @see com.twitter.heron.spi.statemgr.WatchCallback
* @return ExecutionState
*/
ListenableFuture getExecutionState(
WatchCallback watcher, String topologyName);
/**
* Delete the execution state for the given topology
*
* @return Boolean - Success or Failure
*/
ListenableFuture deleteExecutionState(String topologyName);
/**
* Set the scheduler location for the given topology
*
* @return Boolean - Success or Failure
*/
ListenableFuture setSchedulerLocation(
Scheduler.SchedulerLocation location, String topologyName);
/**
* Get the scheduler location for the given topology
*
* @param watcher @see com.twitter.heron.spi.statemgr.WatchCallback
* @return SchedulerLocation
*/
ListenableFuture getSchedulerLocation(
WatchCallback watcher, String topologyName);
/**
* Delete the scheduler location for the given topology
*
* @return Boolean - Success or Failure
*/
ListenableFuture deleteSchedulerLocation(String topologyName);
/**
* Set the Stateful Checkpoints
*
* @return Boolean - Success or Failure
*/
ListenableFuture setStatefulCheckpoints(
CheckpointManager.StatefulConsistentCheckpoints checkpoint, String topologyName);
/**
* Get the Stateful Checkpoints
*
* @return Boolean - Success or Failure
*/
ListenableFuture getStatefulCheckpoints(
WatchCallback watcher, String topologyName);
/**
* Delete the stateful checkpoints for the given topology
*
* @return Boolean - Success or Failure
*/
ListenableFuture deleteStatefulCheckpoints(String topologyName);
}