public class RuntimeContexts extends Object
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, etcRuntimeAction
s
This class is heavily used by xatkit core component to pass RuntimeAction
parameters,
and replace output message variables by their concrete values.
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 and Description |
---|
RuntimeContexts()
Constructs a new empty
RuntimeContexts . |
RuntimeContexts(Configuration configuration)
Constructs a new empty
RuntimeContexts with the given configuration . |
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 . |
public static String VARIABLE_TIMEOUT_KEY
Configuration
key to store maximum time to spend waiting for a context variable (in seconds).public static int DEFAULT_VARIABLE_TIMEOUT_VALUE
public RuntimeContexts()
RuntimeContexts
.
See RuntimeContexts(Configuration)
to construct a RuntimeContexts
with a given
Configuration
.
RuntimeContexts(Configuration)
public RuntimeContexts(Configuration configuration)
RuntimeContexts
with the given configuration
.
The provided Configuration
contains information to customize the RuntimeContexts
behavior, such
as the timeout
to retrieve Future
variables.
configuration
- the Configuration
parameterizing the RuntimeContexts
NullPointerException
- if the provided configuration
is null
public int getVariableTimeout()
RuntimeContexts
can spend waiting for a context variable (in seconds).
This value can be set in this class' Configuration
constructor parameter.
RuntimeContexts
can spend waiting for a context variable (in seconds)public Map<String,Object> setContext(com.xatkit.intent.ContextInstance contextInstance)
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 ContextInstance
s, see
setContext(String, int)
to register a context from String
values.
contextInstance
- the ContextInstance
to setMap
containing the variables of the set contextNullPointerException
- if the provided contextInstance
is null
IllegalArgumentException
- if the provided contextInstance
's definition
is not setpublic Map<String,Object> setContext(String context, int lifespanCount)
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)
.
context
- the name of the context to setlifespanCount
- the lifespan count of the context to setMap
containing the variables of the set contextNullPointerException
- if the provided context
is null
IllegalArgumentException
- if the provided lifespanCount <= 0
setContext(ContextInstance)
,
setContextValue(ContextParameterValue)
,
setContextValue(String, int, String, Object)
,
decrementLifespanCounts()
public void setContextValue(String context, int lifespanCount, String key, Object value)
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)
.
context
- the name of the context to setlifespanCount
- the lifespan count of the context to setkey
- the sub-context key associated to the valuevalue
- the value to storeNullPointerException
- if the provided context
or key
is null
IllegalArgumentException
- if the provided lifespanCount <= 0
getContextVariables(String)
,
getContextValue(String, String)
,
getContextLifespanCount(String)
,
decrementLifespanCounts()
public void setContextValue(com.xatkit.intent.ContextParameterValue contextParameterValue)
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 ContextParameterValue
s received from RuntimeEventProvider
s, see
setContextValue(String, int, String, Object)
to register a context value from String
values.
contextParameterValue
- the ContextParameterValue
to store in the context.NullPointerException
- if the provided contextParameterValue
is null
setContextValue(String, int, String, Object)
public Map<String,Object> getContextVariables(String context)
context
.
This method returns an unmodifiable Map
holding the sub-context variables. To retrieve a specific
variable from RuntimeContexts
see getContextValue(String, String)
.
context
- the sub-context to retrieve the variables fromMap
holding the sub-context variablesNullPointerException
- if the provided context
is null
getContextValue(String, String)
public Object getContextValue(String context, String key)
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)
.
context
- the sub-context to retrieve the variable fromkey
- the sub-context key associated to the valuecontext
value associated to the provided key
, or null
if the key
does not existNullPointerException
- if the provided context
or key
is null
getContextVariables(String)
public int getContextLifespanCount(String context)
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.
context
- the context to retrieve the lifespan count ofcontext
setContextValue(ContextParameterValue)
,
setContextValue(String, int, String, Object)
,
decrementLifespanCounts()
public void decrementLifespanCounts()
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.
public void merge(RuntimeContexts other)
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 RuntimeContexts
s containing them.
However, note that the values stored in the context Map
s are not cloned, meaning that
RuntimeAction
s updating existing values will update them for all the merged
context (see #129).
other
- the RuntimeContexts
to merge into this oneXatkitException
- if the provided RuntimeContexts
defines at least one context
with the
same name as one of the contexts
stored in this RuntimeContexts
public Map<String,Map<String,Object>> getContextMap()
Map
representing the stored context values.Map
representing the stored context valuesCopyright © 2020 SOM Research Lab. All rights reserved.