BotState Class

Package:
com.microsoft.bot.builder
Maven Artifact:
com.microsoft.bot:bot-builder:4.14.3
  • java.lang.Object
    • com.microsoft.bot.builder.BotState

Implements

PropertyManager

public abstract class BotState
implements PropertyManager

Defines a state management object and automates the reading and writing of associated state properties to a storage layer.

Each state management object defines a scope for a storage layer. State properties are created within a state management scope, and the Bot Framework defines these scopes: ConversationState, UserState, and PrivateConversationState. You can define additional scopes for your bot.

Constructor Summary

Constructor Description
BotState(Storage withStorage, String withContextServiceKey)

Initializes a new instance of the BotState class.

Method Summary

Modifier and Type Method and Description
StatePropertyAccessor<T> <T>createProperty(String name)

Creates a named state property within the scope of a BotState and returns an accessor for the property.
protected java.util.concurrent.CompletableFuture<T> <T>getPropertyValue(TurnContext turnContext, String propertyName)

Gets the value of a property from the state cache for this BotState.
java.util.concurrent.CompletableFuture<java.lang.Void> clearState(TurnContext turnContext)

Clears the state cache for this BotState.
java.util.concurrent.CompletableFuture<java.lang.Void> delete(TurnContext turnContext)

Delete any state currently stored in this state scope.
protected java.util.concurrent.CompletableFuture<java.lang.Void> deletePropertyValue(TurnContext turnContext, String propertyName)

Deletes a property from the state cache for this BotState.
com.fasterxml.jackson.databind.JsonNode get(TurnContext turnContext)

Gets a copy of the raw cached data for this BotState from the turn context.
CachedBotState getCachedState(TurnContext turnContext)

Gets the cached bot state instance that wraps the raw cached data for this BotState from the turn context.
abstract java.lang.String getStorageKey(TurnContext turnContext)

When overridden in a derived class, gets the key to use when reading and writing state to and from storage.
java.util.concurrent.CompletableFuture<java.lang.Void> load(TurnContext turnContext)

Populates the state cache for this BotState from the storage layer.
java.util.concurrent.CompletableFuture<java.lang.Void> load(TurnContext turnContext, boolean force)

Reads in the current state object and caches it in the context object for this turn.
java.util.concurrent.CompletableFuture<java.lang.Void> saveChanges(TurnContext turnContext)

Writes the state cache for this BotState to the storage layer.
java.util.concurrent.CompletableFuture<java.lang.Void> saveChanges(TurnContext turnContext, boolean force)

Writes the state cache for this BotState to the storage layer.
protected java.util.concurrent.CompletableFuture<java.lang.Void> setPropertyValue(TurnContext turnContext, String propertyName, Object value)

Sets the value of a property in the state cache for this BotState.

Methods inherited from java.lang.Object

java.lang.Object.clone java.lang.Object.equals java.lang.Object.finalize java.lang.Object.getClass java.lang.Object.hashCode java.lang.Object.notify java.lang.Object.notifyAll java.lang.Object.toString java.lang.Object.wait java.lang.Object.wait java.lang.Object.wait

Constructor Details

BotState

public BotState(Storage withStorage, String withContextServiceKey)

Initializes a new instance of the BotState class.

Parameters:

withStorage - The storage provider to use.
withContextServiceKey - The key for the state cache for this BotState.

Throws:

java.lang.IllegalArgumentException - Null Storage or empty service key arguments.

Method Details

<T>createProperty

public StatePropertyAccessor createProperty(String name)

Creates a named state property within the scope of a BotState and returns an accessor for the property.

Parameters:

name - name of property.

Returns:

A StatePropertyAccessor<T> for the property.

Throws:

java.lang.IllegalArgumentException - Empty name

<T>getPropertyValue

protected CompletableFuture getPropertyValue(TurnContext turnContext, String propertyName)

Gets the value of a property from the state cache for this BotState.

Parameters:

turnContext - The context object for this turn.
propertyName - The name of the property to get.

Returns:

A task that represents the work queued to execute. If the task is successful, the result contains the property value.

clearState

public CompletableFuture clearState(TurnContext turnContext)

Clears the state cache for this BotState.

This method clears the state cache in the turn context. Call saveChanges(TurnContext turnContext, boolean force) to persist this change in the storage layer.

Parameters:

turnContext - The context object for this turn.

Returns:

A task that represents the work queued to execute.

delete

public CompletableFuture delete(TurnContext turnContext)

Delete any state currently stored in this state scope.

Parameters:

turnContext - The context object for this turn.

Returns:

A task that represents the work queued to execute.

deletePropertyValue

protected CompletableFuture deletePropertyValue(TurnContext turnContext, String propertyName)

Deletes a property from the state cache for this BotState.

Parameters:

turnContext - The context object for this turn.
propertyName - The name of the property to delete.

Returns:

A task that represents the work queued to execute.

get

public JsonNode get(TurnContext turnContext)

Gets a copy of the raw cached data for this BotState from the turn context.

Parameters:

turnContext - The context object for this turn.

Returns:

A JSON representation of the cached state.

getCachedState

public BotState.CachedBotState getCachedState(TurnContext turnContext)

Gets the cached bot state instance that wraps the raw cached data for this BotState from the turn context.

Parameters:

turnContext - The context object for this turn.

Returns:

The cached bot state instance.

getStorageKey

public abstract String getStorageKey(TurnContext turnContext)

When overridden in a derived class, gets the key to use when reading and writing state to and from storage.

Parameters:

turnContext - The context object for this turn.

Returns:

The storage key.

Throws:

java.lang.IllegalArgumentException - TurnContext doesn't contain all the required data.

load

public CompletableFuture load(TurnContext turnContext)

Populates the state cache for this BotState from the storage layer.

Parameters:

turnContext - The context object for this turn.

Returns:

A task that represents the work queued to execute.

load

public CompletableFuture load(TurnContext turnContext, boolean force)

Reads in the current state object and caches it in the context object for this turn.

Parameters:

turnContext - The context object for this turn.
force - true to overwrite any existing state cache; or false to load state from storage only if the cache doesn't already exist.

Returns:

A task that represents the work queued to execute.

saveChanges

public CompletableFuture saveChanges(TurnContext turnContext)

Writes the state cache for this BotState to the storage layer.

Parameters:

turnContext - The context object for this turn.

Returns:

A task that represents the work queued to execute.

saveChanges

public CompletableFuture saveChanges(TurnContext turnContext, boolean force)

Writes the state cache for this BotState to the storage layer.

Parameters:

turnContext - The context object for this turn.
force - true to save the state cache to storage; or false to save state to storage only if a property in the cache has changed.

Returns:

A task that represents the work queued to execute.

setPropertyValue

protected CompletableFuture setPropertyValue(TurnContext turnContext, String propertyName, Object value)

Sets the value of a property in the state cache for this BotState.

Parameters:

turnContext - The context object for this turn.
propertyName - The name of the property to set.
value - The value to set on the property.

Returns:

A task that represents the work queued to execute.

Applies to