RuntimeContexts (Xatkit Runtime 4.0.1-SNAPSHOT API)

java.lang.Object
- com.xatkit.core.session.RuntimeContexts

```
public class RuntimeContexts
extends Object
```
A variable container bound to a XatkitSession.
This class stores the different variables that can be set during user input processing and accessed by executed RuntimeAction. RuntimeContexts is used to store:
- RuntimeEventProvider values such as the user name, the channel where the message was received, etc
- Intent recognition values, that are computed by the Intent recognition engine and used to pass information between messages
- Action values, that are returned by RuntimeActions
This class is heavily used by xatkit core component to pass RuntimeAction parameters, and replace output message variables by their concrete values.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`DEFAULT_VARIABLE_TIMEOUT_VALUE` The default amount of time to spend waiting for a context variable (in seconds).
`static String`	`VARIABLE_TIMEOUT_KEY` The `Configuration` key to store maximum time to spend waiting for a context variable (in seconds).

Constructor Summary

Constructors
Constructor and Description
`RuntimeContexts()` Constructs a new empty `RuntimeContexts`.
`RuntimeContexts(Configuration configuration)` Constructs a new empty `RuntimeContexts` with the given `configuration`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`decrementLifespanCounts()` Decrements the lifespanCount of all the stored contexts, and remove them if there lifespanCount decreases to 0.
`int`	`getContextLifespanCount(String context)` Returns the lifespan count of the provided `context`.
`Map<String,Map<String,Object>>`	`getContextMap()` Returns an unmodifiable `Map` representing the stored context values.
`Object`	`getContextValue(String context, String key)` Returns the `context` value associated to the provided `key`.
`Map<String,Object>`	`getContextVariables(String context)` Returns all the variables stored in the given `context`.
`Map<String,Integer>`	`getLifespanCountsMap()` Returns an unmodifiable `Map` representing the stored lifespan counts.
`int`	`getVariableTimeout()` Returns the amount of time the `RuntimeContexts` can spend waiting for a context variable (in seconds).
`void`	`merge(RuntimeContexts other)` Merges the provided `other` `RuntimeContexts` into this one.
`Map<String,Object>`	`setContext(com.xatkit.intent.ContextInstance contextInstance)` Sets the context associated to the provided `contextInstance`.
`Map<String,Object>`	`setContext(String context, int lifespanCount)` Sets the provided `context` with the given `lifespanCount`.
`void`	`setContextValue(com.xatkit.intent.ContextParameterValue contextParameterValue)` Stores the provided `contextParameterValue` in the context.
`void`	`setContextValue(String context, int lifespanCount, String key, Object value)` Stores the provided `value` in the given `context` with the provided `key` and `lifespanCount`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - VARIABLE_TIMEOUT_KEY
```
public static String VARIABLE_TIMEOUT_KEY
```
    The Configuration key to store maximum time to spend waiting for a context variable (in seconds).
  - DEFAULT_VARIABLE_TIMEOUT_VALUE
```
public static int DEFAULT_VARIABLE_TIMEOUT_VALUE
```
    The default amount of time to spend waiting for a context variable (in seconds).
- Constructor Detail
  - RuntimeContexts
```
public RuntimeContexts()
```
    Constructs a new empty RuntimeContexts.
    See RuntimeContexts(Configuration) to construct a RuntimeContexts with a given Configuration.
    
    See Also:
    
    RuntimeContexts(Configuration)
  - RuntimeContexts
```
public RuntimeContexts(Configuration configuration)
```
    Constructs a new empty RuntimeContexts with the given configuration.
    The provided Configuration contains information to customize the RuntimeContexts behavior, such as the timeout to retrieve Future variables.
    
    Parameters:
    
    configuration - the Configuration parameterizing the RuntimeContexts
    
    Throws:
    
    NullPointerException - if the provided configuration is null
- Method Detail
  - getVariableTimeout
```
public int getVariableTimeout()
```
    Returns the amount of time the RuntimeContexts can spend waiting for a context variable (in seconds).
    This value can be set in this class' Configuration constructor parameter.
    
    Returns:
    
    the amount of time the RuntimeContexts can spend waiting for a context variable (in seconds)
  - setContext
```
public Map<String,Object> setContext(com.xatkit.intent.ContextInstance contextInstance)
```
    Sets the context associated to the provided contextInstance.
    This method retrieves the name of the context to set from the provided ContextInstance by navigating its definition reference. Note that passing a contextInstance without definition to this method will throw an IllegalArgumentException.
    This method is used as syntactic sugar to register ContextInstances, see setContext(String, int) to register a context from String values.
    
    Parameters:
    
    contextInstance - the ContextInstance to set
    
    Returns:
    
    the Map containing the variables of the set context
    
    Throws:
    
    NullPointerException - if the provided contextInstance is null
    
    IllegalArgumentException - if the provided contextInstance's definition is not set
  - setContext
```
public Map<String,Object> setContext(String context,
                                     int lifespanCount)
```
    Sets the provided context with the given lifespanCount.
    Note: the context lifespan count is only updated if lifespanCount > #getContextLifespanCount (context). Context lifespan counts can only be decremented by calling decrementLifespanCounts(). This architecture ensures the global lifespan count consistency among context variables.
    As an example, calling setContextValue("slack", 5, "username", "myUsername") sets the variable username with the value myUsername in the slack context, and sets its lifespan count to 5.
    To retrieve all the variables of a given sub-context see getContextVariables(String).
    
    Parameters:
    
    context - the name of the context to set
    
    lifespanCount - the lifespan count of the context to set
    
    Returns:
    
    the Map containing the variables of the set context
    
    Throws:
    
    NullPointerException - if the provided context is null
    
    IllegalArgumentException - if the provided lifespanCount <= 0
    
    See Also:
    
    setContext(ContextInstance), setContextValue(ContextParameterValue), setContextValue(String, int, String, Object), decrementLifespanCounts()
  - setContextValue
```
public void setContextValue(String context,
                            int lifespanCount,
                            String key,
                            Object value)
```
    Stores the provided value in the given context with the provided key and lifespanCount.
    Note: the context lifespan count is only updated if lifespanCount > #getContextLifespanCount (context). Context lifespan counts can only be decremented by calling decrementLifespanCounts(). This architecture ensures the global lifespan count consistency among context variables.
    As an example, calling setContextValue("slack", 5, "username", "myUsername") sets the variable username with the value myUsername in the slack context, and sets its lifespan count to 5.
    To retrieve all the variables of a given sub-context see getContextVariables(String).
    
    Parameters:
    
    context - the name of the context to set
    
    lifespanCount - the lifespan count of the context to set
    
    key - the sub-context key associated to the value
    
    value - the value to store
    
    Throws:
    
    NullPointerException - if the provided context or key is null
    
    IllegalArgumentException - if the provided lifespanCount <= 0
    
    See Also:
    
    getContextVariables(String), getContextValue(String, String), getContextLifespanCount(String), decrementLifespanCounts()
  - setContextValue
```
public void setContextValue(com.xatkit.intent.ContextParameterValue contextParameterValue)
```
    Stores the provided contextParameterValue in the context.
    This method extracts the context name and parameter key from the provided ContextParameterValue, by navigating its ContextParameter and Context references. This method is used as syntactic sugar to register ContextParameterValues received from RuntimeEventProvider s, see setContextValue(String, int, String, Object) to register a context value from String values.
    
    Parameters:
    
    contextParameterValue - the ContextParameterValue to store in the context.
    
    Throws:
    
    NullPointerException - if the provided contextParameterValue is null
    
    See Also:
    
    setContextValue(String, int, String, Object)
  - getContextVariables
```
public Map<String,Object> getContextVariables(String context)
```
    Returns all the variables stored in the given context.
    This method returns an unmodifiable Map holding the sub-context variables. To retrieve a specific variable from RuntimeContexts see getContextValue(String, String).
    
    Parameters:
    
    context - the sub-context to retrieve the variables from
    
    Returns:
    
    an unmodifiable Map holding the sub-context variables
    
    Throws:
    
    NullPointerException - if the provided context is null
    
    See Also:
    
    getContextValue(String, String)
  - getContextValue
```
public Object getContextValue(String context,
                              String key)
```
    Returns the context value associated to the provided key.
    As an example, calling getContextValue("slack", "username") returns the value of the username variable stored in the slack sub-context.
    To retrieve all the variables of a given sub-context see getContextVariables(String).
    
    Parameters:
    
    context - the sub-context to retrieve the variable from
    
    key - the sub-context key associated to the value
    
    Returns:
    
    the context value associated to the provided key, or null if the key does not exist
    
    Throws:
    
    NullPointerException - if the provided context or key is null
    
    See Also:
    
    getContextVariables(String)
  - getContextLifespanCount
```
public int getContextLifespanCount(String context)
```
    Returns the lifespan count of the provided context.
    Context lifespan counts are set by setContextValue(String, int, String, Object), and decrementing after each user input by decrementLifespanCounts(), and are synchronized with the IntentRecognitionProvider's remote context lifespan counts.
    
    Parameters:
    
    context - the context to retrieve the lifespan count of
    
    Returns:
    
    the lifespan count of the provided context
    
    See Also:
    
    setContextValue(ContextParameterValue), setContextValue(String, int, String, Object), decrementLifespanCounts()
  - decrementLifespanCounts
```
public void decrementLifespanCounts()
```
    Decrements the lifespanCount of all the stored contexts, and remove them if there lifespanCount decreases to 0.
    LifespanCounts corresponds to the number of user inputs that can be handled before removing the variable from the current context. This method is called after each user input to take into account the new interaction and decrement the lifespan counters from the live contexts.
  - merge
```
public void merge(RuntimeContexts other)
```
    Merges the provided other RuntimeContexts into this one.
    This method adds all the contexts and values of the provided other RuntimeContexts to this one, performing a deep copy of the underlying Map structure, ensuring that future updates on the other RuntimeContexts will not be applied on this one (such as value and context additions/deletions).
    Lifespan counts are also copied from the other RuntimeContexts to this one, ensuring that their lifespan remains consistent in all the RuntimeContextss containing them.
    However, note that the values stored in the context Maps are not cloned, meaning that RuntimeActions updating existing values will update them for all the merged context (see #129).
    
    Parameters:
    
    other - the RuntimeContexts to merge into this one
    
    Throws:
    
    XatkitException - if the provided RuntimeContexts defines at least one context with the same name as one of the contexts stored in this RuntimeContexts
  - getContextMap
```
public Map<String,Map<String,Object>> getContextMap()
```
    Returns an unmodifiable Map representing the stored context values.
    
    Returns:
    
    an unmodifiable Map representing the stored context values
  - getLifespanCountsMap
```
public Map<String,Integer> getLifespanCountsMap()
```
    Returns an unmodifiable Map representing the stored lifespan counts.
    
    Returns:
    
    an unmodifiable Map representing the stored lifespan counts

Class RuntimeContexts

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

VARIABLE_TIMEOUT_KEY

DEFAULT_VARIABLE_TIMEOUT_VALUE

Constructor Detail

RuntimeContexts

RuntimeContexts

Method Detail

getVariableTimeout

setContext

setContext

setContextValue

setContextValue

getContextVariables

getContextValue

getContextLifespanCount

decrementLifespanCounts

merge

getContextMap

getLifespanCountsMap