com.mesosphere.sdk.state

Class StateStore

java.lang.Object

com.mesosphere.sdk.state.StateStore

public class StateStore
extends java.lang.Object

A StateStore stores the state of a service, including tasks' TaskInfo and TaskStatus objects. Each distinct Task is expected to have a unique Task Name, determined by the service developer.

TaskInfo objects should be persisted when a Task is launched or when reserved resources associated with a potential future Task launch should be recorded.

TaskStatus is reported by Mesos to Frameworks at various points including at Task Reconciliation and when Tasks change state. The TaskStatus of a Task should be recorded so that the state of a Framework's Tasks can be queried.

The structure used in the underlying persister is as follows:
rootPath/
-> FrameworkID
-> Tasks/
-> [TaskName-0]/
-> TaskInfo
-> TaskStatus
-> [TaskName-1]/
-> TaskInfo
-> [TaskName-2]/
-> TaskInfo
-> TaskStatus
-> ...

Field Summary

Fields

Modifier and Type	Field and Description
protected Persister	persister

Constructor Summary

Constructors

Constructor and Description
StateStore(Persister persister) Creates a new StateStore which uses the provided Persister to access state data.

Method Summary

Modifier and Type	Method and Description
void	clearAllData() Clears the root service node, leaving just the root node behind.
void	clearFrameworkId() Removes any previously stored FrameworkID or does nothing if no FrameworkID was previously stored.
void	clearProperty(java.lang.String key) Clears a given property from the StateStore, or does nothing if no such property exists.
void	clearTask(java.lang.String taskName) Removes all data associated with a particular Task including any stored TaskInfo and/or TaskStatus.
java.util.Optional<Protos.FrameworkID>	fetchFrameworkId() Fetches the previously stored FrameworkID, or returns an empty Optional if no FrameworkId was previously stored.
GoalStateOverride.Status	fetchGoalOverrideStatus(java.lang.String taskName) Retrieves the goal state override status of a particular task.
byte[]	fetchProperty(java.lang.String key) Fetches the value byte array, stored against the Property key, or throws an error if no matching key is found.
java.util.Collection<java.lang.String>	fetchPropertyKeys() Fetches the list of Property keys, or an empty list if none are found.
java.util.Optional<Protos.TaskStatus>	fetchStatus(java.lang.String taskName) Fetches the TaskStatus for a particular Task, or returns an empty Optional if no matching status is found.
java.util.Collection<Protos.TaskStatus>	fetchStatuses() Fetches all Protos.TaskStatuses from the underlying storage, or an empty list if none are found.
java.util.Optional<Protos.TaskInfo>	fetchTask(java.lang.String taskName) Fetches the TaskInfo for a particular Task, or returns an empty Optional if no matching task is found.
java.util.Collection<java.lang.String>	fetchTaskNames() Fetches all the Task names listed in the underlying storage.
java.util.Collection<Protos.TaskInfo>	fetchTasks() Fetches and returns all Protos.TaskInfos from the underlying storage, or an empty list if none are found.
protected static java.lang.String	getGoalOverridePath(java.lang.String taskName)
protected static java.lang.String	getGoalOverrideStatusPath(java.lang.String taskName)
Persister	getPersister() Returns the underlying Persister object for direct access.
protected static java.lang.String	getTaskInfoPath(java.lang.String taskName)
protected static java.lang.String	getTaskPath(java.lang.String taskName)
protected static java.lang.String	getTaskStatusPath(java.lang.String taskName)
void	storeFrameworkId(Protos.FrameworkID fwkId) Stores the FrameworkID for a framework so on Scheduler restart re-registration may occur.
void	storeGoalOverrideStatus(java.lang.String taskName, GoalStateOverride.Status status) Stores the goal state override status of a particular Task.
void	storeProperty(java.lang.String key, byte[] value) Stores an arbitrary key/value pair.
void	storeStatus(java.lang.String taskName, Protos.TaskStatus status) Stores the TaskStatus of a particular Task.
void	storeTasks(java.util.Collection<Protos.TaskInfo> tasks) Stores TaskInfo objects representing tasks which are desired by the framework.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

persister

protected final Persister persister

Constructor Detail

StateStore

public StateStore(Persister persister)

Creates a new StateStore which uses the provided Persister to access state data.

Parameters:

persister - The persister which holds the state data

Method Detail

storeFrameworkId

public void storeFrameworkId(Protos.FrameworkID fwkId)
                      throws StateStoreException

Stores the FrameworkID for a framework so on Scheduler restart re-registration may occur.

Parameters:

fwkId - FrameworkID to be store

Throws:

StateStoreException - when storing the FrameworkID fails

clearFrameworkId

public void clearFrameworkId()
                      throws StateStoreException

Removes any previously stored FrameworkID or does nothing if no FrameworkID was previously stored.

Throws:

StateStoreException - when clearing a FrameworkID fails

fetchFrameworkId

public java.util.Optional<Protos.FrameworkID> fetchFrameworkId()
                                                        throws StateStoreException

Fetches the previously stored FrameworkID, or returns an empty Optional if no FrameworkId was previously stored.

Returns:

The previously stored FrameworkID, or an empty Optional indicating the FrameworkID has not been set.

Throws:

StateStoreException - when fetching the FrameworkID fails

storeTasks

public void storeTasks(java.util.Collection<Protos.TaskInfo> tasks)
                throws StateStoreException

Stores TaskInfo objects representing tasks which are desired by the framework. This must be called before storeStatus(String, Protos.TaskStatus) for any given task id, and it must behave as an atomic transaction: On success, everything is written, while on failure nothing is written.

Parameters:

tasks - Tasks to be stored, which each meet the above requirements

Throws:

StateStoreException - when persisting TaskInfo information fails, or if its TaskId is malformed

storeStatus

public void storeStatus(java.lang.String taskName,
                        Protos.TaskStatus status)
                 throws StateStoreException

Stores the TaskStatus of a particular Task. The Protos.TaskInfo for this exact task MUST have already been written via storeTasks(Collection) beforehand. The TaskId must be well-formatted as produced by CommonIdUtils.toTaskId(String).

Parameters:

status - The status to be stored, which meets the above requirements

Throws:

StateStoreException - if storing the TaskStatus fails, or if its TaskId is malformed, or if its matching TaskInfo wasn't stored first

clearTask

public void clearTask(java.lang.String taskName)
               throws StateStoreException

Removes all data associated with a particular Task including any stored TaskInfo and/or TaskStatus.

Parameters:

taskName - The name of the task to be cleared

Throws:

StateStoreException - when clearing the indicated Task's information fails

fetchTaskNames

public java.util.Collection<java.lang.String> fetchTaskNames()
                                                      throws StateStoreException

Fetches all the Task names listed in the underlying storage. Note that these should always have a TaskInfo, but may lack TaskStatus.

Returns:

All the Task names stored so far, or an empty list if none are found

Throws:

StateStoreException - when fetching the data fails

fetchTasks

public java.util.Collection<Protos.TaskInfo> fetchTasks()
                                                 throws StateStoreException

Fetches and returns all Protos.TaskInfos from the underlying storage, or an empty list if none are found. This list should be a superset of the list returned by fetchStatuses().

Returns:

All TaskInfos

Throws:

StateStoreException - if fetching the TaskInfo information otherwise fails

fetchTask

public java.util.Optional<Protos.TaskInfo> fetchTask(java.lang.String taskName)
                                              throws StateStoreException

Fetches the TaskInfo for a particular Task, or returns an empty Optional if no matching task is found.

Parameters:

taskName - The name of the Task

Returns:

The corresponding TaskInfo object

Throws:

StateStoreException - if no data was found for the requested name, or if fetching the TaskInfo otherwise fails

fetchStatuses

public java.util.Collection<Protos.TaskStatus> fetchStatuses()
                                                      throws StateStoreException

Fetches all Protos.TaskStatuses from the underlying storage, or an empty list if none are found. Note that this list may have fewer entries than fetchTasks() if some tasks are lacking statuses.

Returns:

The TaskStatus objects associated with all tasks

Throws:

StateStoreException - if fetching the TaskStatus information fails

fetchStatus

public java.util.Optional<Protos.TaskStatus> fetchStatus(java.lang.String taskName)
                                                  throws StateStoreException

Fetches the TaskStatus for a particular Task, or returns an empty Optional if no matching status is found. A given task may sometimes have Protos.TaskInfo while lacking Protos.TaskStatus.

Parameters:

taskName - The name of the Task which should have its status retrieved

Returns:

The TaskStatus associated with a particular Task

Throws:

StateStoreException - if no data was found for the requested name, or if fetching the TaskStatus information otherwise fails

storeProperty

public void storeProperty(java.lang.String key,
                          byte[] value)
                   throws StateStoreException

Stores an arbitrary key/value pair.

Parameters:

key - must be a non-blank String without any forward slashes ('/')

value - The value should be a byte array no larger than 1MB (1024 * 1024 bytes)

Throws:

StateStoreException - if the key or value fail validation, or if storing the data otherwise fails

See Also:

validateKey(String), validateValue(byte[])

fetchProperty

public byte[] fetchProperty(java.lang.String key)
                     throws StateStoreException

Fetches the value byte array, stored against the Property key, or throws an error if no matching key is found.

Parameters:

key - must be a non-blank String without any forward slashes ('/')

Throws:

StateStoreException - if no data was found for the requested key, or if fetching the data otherwise fails

See Also:

validateKey(String)

fetchPropertyKeys

public java.util.Collection<java.lang.String> fetchPropertyKeys()
                                                         throws StateStoreException

Fetches the list of Property keys, or an empty list if none are found.

Throws:

StateStoreException - if fetching the list otherwise fails

clearProperty

public void clearProperty(java.lang.String key)
                   throws StateStoreException

Clears a given property from the StateStore, or does nothing if no such property exists.

Parameters:

key - must be a non-blank String without any forward slashes ('/')

Throws:

StateStoreException - if key validation fails or clearing the entry fails

storeGoalOverrideStatus

public void storeGoalOverrideStatus(java.lang.String taskName,
                                    GoalStateOverride.Status status)
                             throws StateStoreException

Stores the goal state override status of a particular Task. The Protos.TaskInfo for this exact task MUST have already been written via storeTasks(Collection) beforehand.

Throws:

StateStoreException - in the event of a storage error

fetchGoalOverrideStatus

public GoalStateOverride.Status fetchGoalOverrideStatus(java.lang.String taskName)
                                                 throws StateStoreException

Retrieves the goal state override status of a particular task. A lack of override will result in a GoalStateOverride.Status with override=NONE and state=NONE.

Throws:

StateStoreException - in the event of a storage error

clearAllData

public void clearAllData()
                  throws StateStoreException

Clears the root service node, leaving just the root node behind.

Throws:

StateStoreException

getPersister

public Persister getPersister()

Returns the underlying Persister object for direct access.

Returns:

getTaskInfoPath

protected static java.lang.String getTaskInfoPath(java.lang.String taskName)

getTaskStatusPath

protected static java.lang.String getTaskStatusPath(java.lang.String taskName)

getGoalOverridePath

protected static java.lang.String getGoalOverridePath(java.lang.String taskName)

getGoalOverrideStatusPath

protected static java.lang.String getGoalOverrideStatusPath(java.lang.String taskName)

getTaskPath

protected static java.lang.String getTaskPath(java.lang.String taskName)