Class EngineAccess
- Object
-
- EngineAccess
-
public class EngineAccess extends Object
Provides controlled access for scripts to internal engine data.An instance of this class is accessible from solution scripting via the predefined variable '
engineAccess
' or its convenience alias '_
' (underline).Methods provided by this class may not be called in certain script events. See this table for details.
- Version:
- 7.5.0
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
EngineAccess.Data
class
EngineAccess.DialogHistoryUtilities
This class provides utility methods for modification of the dialog history data.static class
EngineAccess.HistoryItem
Data of a session history entry.static class
EngineAccess.LangCompMatch
Entry type of the list returned byfindMatchingLanguageComponents(java.lang.String, boolean)
.static class
EngineAccess.WordListType
Result types known to methods that return word processing data.
-
Field Summary
Fields Modifier and Type Field Description static EngineAccess.WordListType
FINAL
Shortcut toEngineAccess.WordListType.FINAL
.static EngineAccess.WordListType
FINALIZED
Deprecated.useFINAL
insteadstatic int
LIFESPAN_SESSION
Constant for methodsetSessVarLifespan(String, int)
, lifespan parameter.static EngineAccess.WordListType
ORIGINAL
Shortcut toEngineAccess.WordListType.ORIGINAL
.static EngineAccess.WordListType
ORIGINAL_PACKED
Shortcut toEngineAccess.WordListType.ORIGINAL_PACKED
.static EngineAccess.WordListType
RAW
Deprecated.useORIGINAL
insteadstatic EngineAccess.WordListType
RAW_PACKED
Deprecated.useORIGINAL_PACKED
insteadstatic EngineAccess.WordListType
SIMPLIFIED
Shortcut toEngineAccess.WordListType.SIMPLIFIED
.static EngineAccess.WordListType
SIMPLIFIED_PACKED
Shortcut toEngineAccess.WordListType.SIMPLIFIED_PACKED
.
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
abortActiveFlow(String _sFlowInstanceId)
Marks the flow with the given flow instance ID for premature termination.String
autoCorrect(String _sWord)
Returns the auto-corrected version of the given single word, or just the simplified form of the given word if an auto-correction isn't available for it.Annotation
createInputAnnotation(String _sName, int _iSentenceIndex, Set<Integer> _zWordIndices, Map<String,Object> _mVariables)
Creates a user inputAnnotation
object with the given data.String[]
divideIntoSentences(String _sText)
Divides the given text into substrings according to the sentence dividing rules of the engine.String[]
divideIntoWords(String _sText)
Returns the same result as the following method invocation:String[]
divideIntoWords(String _sText, EngineAccess.WordListType _eWordListType)
Divides the given text into words according to the word dividing rules of the engine.List<EngineAccess.LangCompMatch>
findMatchingLanguageComponents(String _sSentenceText, boolean _bUseCurrentSession)
Tests all language objects and entities against the given sentence text and returns a list of matches.List<EngineAccess.LangCompMatch>
findMatchingLanguageObjects(String _sSentenceText, boolean _bUseCurrentSession)
Deprecated.List<List<EngineAccess.Data.ActiveFlow>>
getActiveFlows()
Returns a snapshot of the current active flows stack.String
getApplicationName()
Returns the name of the selected engine application.List<EngineAccess.HistoryItem>
getDialogHistory()
Returns a snapshot of the session history.int
getDialogHistoryLength()
Returns the number of items in the session history (e.g.EngineAccess.DialogHistoryUtilities
getDialogHistoryUtilities()
Returns theEngineAccess.DialogHistoryUtilities
instance which provides convenient methods for dialog history modification.Map<String,Object>
getEndDialogChangedVariables()
Returns an unmodifiable map of the session scope changed variables, generated during session termination processing.Map<String,String>
getEndDialogLogVariables()
Returns an unmodifiable map of the session scope log variables, generated during session termination processing.Map<String,String>
getEndDialogMetadata()
Returns an unmodifiable map of the session scope metadata, generated during session termination processing.int
getFlowTriggerOrderGroupValue(String _sOrderGroupName)
Returns the value of the flow trigger order group with the given name.AnnotationsI
getInputAnnotations()
Returns the user input annotations generated by the input processors or added by scripting.String
getLangObjVariable(String _sName)
Returns the value of a language object variable with the given name, ornull
if no such language object variable exists.Map<String,String>
getLangObjVariables()
Returns the map of the available language object variables and their values.List<Integer>
getMatchRangeStartIndices()
Returns aList
with one or more sentence word indices.String
getNextTransactionId()
Returns the ID string to be used for the next user request transaction.int
getNotUsedRawWordCount()
Deprecated.String[]
getNotUsedRawWords()
Deprecated.UsegetNotUsedWords()
.SortedSet<Integer>
getNotUsedWordIndices()
Returns the positions of the sentence words not used to fulfill a condition.List<String>
getNotUsedWords()
Returns the same result as the following method invocation:List<String>
getNotUsedWords(EngineAccess.WordListType _eWordListType)
Returns the sentence words not used to fulfill a condition.String
getOutputEmotion()
Returns the output emotion of the final response to be returned by the engine.String
getOutputParameter(String _sName)
Returns the value of an output parameter with the given name, ornull
if no such output parameter exists.Map<String,String>
getOutputParameters()
Returns the map of the available output parameters and their values.String
getOutputText()
Returns the output text of the final response to be returned by the engine.String
getOutputURL()
Returns the output URL of the final response to be returned by the engine.List<Map<String,Object>>
getProcessingPath()
Returns an unmodifiable copy of the vertex processing path for the current turn.String
getProperty(String _sKey)
Returns the same result as the following method invocation:getProperty(_sKey, "")
String
getProperty(String _sKey, String _sDefault)
Returns the value of a specified property as read from the engine property files.int
getSentenceCount()
Returns the number of sentences in the user input.int
getSentenceIndex()
Returns the index of the user input sentence currently processed or associated with the chosen answer.List<SentenceI>
getSentences()
Returns an unmodifiable view of the sentences and their words, generated from the user input text.String
getSentenceText()
Returns the text of the user input sentence currently processed or associated with the chosen answer.List<Integer>
getSentenceWordBeginnings()
Returns the same result as the following method invocation:List<Integer>
getSentenceWordBeginnings(EngineAccess.WordListType _eWordListType)
Returns the beginning character indices of the words of the user input sentence currently processed or associated with the chosen answer.int
getSentenceWordCount()
Deprecated.UsegetSentenceWords().length
instead.int
getSentenceWordCount(EngineAccess.WordListType _eWordListType)
Deprecated.UsegetSentenceWords(EngineAccess.WordListType).length
instead.String[]
getSentenceWords()
Returns the same result as the following method invocation:String[]
getSentenceWords(EngineAccess.WordListType _eWordListType)
Returns the words of the user input sentence currently processed or associated with the chosen answer.String
getSessionId()
Returns the ID string of the current session context.int
getSessVarLifespan(String _sVarName)
Returns the remaining lifespan of the specified session variable.EngineAccess.Data.ActiveFlow
getThisFlow()
Returns the flow currently in scope of flow processing.EngineAccess.Data.ActiveFlow
getTopFlow()
Returns the topmost element of the active flows stack, ornull
if the stack is empty.EngineAccess.Data.ActiveFlow
getTopNormalFlow()
Returns the topmost normal flow of the active flows stack, ornull
if the stack is empty.String
getTransactionId()
Returns the ID string of the current user request transaction.int
getUsedRawWordCount()
Deprecated.String[]
getUsedRawWords()
Deprecated.UsegetUsedWords()
.SortedSet<Integer>
getUsedWordIndices()
Returns the positions of sentence words used to fulfill a condition.List<String>
getUsedWords()
Returns the same result as the following method invocation:List<String>
getUsedWords(EngineAccess.WordListType _eWordListType)
Returns the sentence words used to fulfill a condition.String
getUserInputText()
Returns the user input text.int
getUserInputWordCount()
Deprecated.UsegetUserInputWords().length
instead.int
getUserInputWordCount(EngineAccess.WordListType _eWordListType)
Deprecated.UsegetUserInputWords(EngineAccess.WordListType).length
instead.String[]
getUserInputWords()
Returns the same result as the following method invocation:String[]
getUserInputWords(EngineAccess.WordListType _eWordListType)
Returns the words of the user input text.void
putLogVariable(String _sKey, String _sValue)
Puts a key/value pair (a log variable) into the set of log variables to be written to the session log.void
putOutputParameter(String _sName, String _sValue)
Sets the output parameter with the given name and value in the collection of output parameters.void
setOutputEmotion(String _sEmotion)
Sets the emotion of the final response to be returned by the engine.void
setOutputText(String _sText)
Sets the text of the final response to be returned by the engine.void
setOutputURL(String _sURL)
Sets the URL of the final response to be returned by the engine.void
setSessVarLifespan(String _sVarName, int _iLifespan)
Sets the lifespan of the specified session variable to the given number of user input turns.void
setSuppressResumePrompt(boolean _bSuppress)
This method is for internal use only.void
setUserInputText(String _sText)
Sets the user input text to be used for flow evaluation.String
similarWord(String _sWord)
Searches the internal dictionary for the simplified version of the given word and returns the following result: the simplified version of the word (in lower case), if it exists in the internal dictionary; the alphabetically first of the most similar words from the dictionary, as long as the spelling tolerance threshold isn't exceeded; or thenull
object if a sufficiently similar word isn't found.String
simplify(String _sWord)
Returns the simplified version of a specified text (not necessarily a single word).
-
-
-
Field Detail
-
RAW
@Deprecated public static final EngineAccess.WordListType RAW
Deprecated.useORIGINAL
instead- Since:
- 1.0
-
ORIGINAL
public static final EngineAccess.WordListType ORIGINAL
Shortcut toEngineAccess.WordListType.ORIGINAL
.- Since:
- 4.0.3
-
RAW_PACKED
@Deprecated public static final EngineAccess.WordListType RAW_PACKED
Deprecated.useORIGINAL_PACKED
instead- Since:
- 1.0
-
ORIGINAL_PACKED
public static final EngineAccess.WordListType ORIGINAL_PACKED
Shortcut toEngineAccess.WordListType.ORIGINAL_PACKED
.- Since:
- 4.0.3
-
SIMPLIFIED
public static final EngineAccess.WordListType SIMPLIFIED
Shortcut toEngineAccess.WordListType.SIMPLIFIED
.- Since:
- 1.0
-
SIMPLIFIED_PACKED
public static final EngineAccess.WordListType SIMPLIFIED_PACKED
Shortcut toEngineAccess.WordListType.SIMPLIFIED_PACKED
.- Since:
- 1.0
-
FINALIZED
@Deprecated public static final EngineAccess.WordListType FINALIZED
Deprecated.useFINAL
instead- Since:
- 1.0
-
FINAL
public static final EngineAccess.WordListType FINAL
Shortcut toEngineAccess.WordListType.FINAL
.- Since:
- 4.0.3
-
LIFESPAN_SESSION
public static final int LIFESPAN_SESSION
Constant for methodsetSessVarLifespan(String, int)
, lifespan parameter.- Since:
- 1.2
-
-
Method Detail
-
getApplicationName
public String getApplicationName()
Returns the name of the selected engine application.- Since:
- 1.0
-
getSessionId
public String getSessionId()
Returns the ID string of the current session context.- Throws:
UnsupportedOperationException
- if session data isn't available in the calling script context- Since:
- 1.0
-
getTransactionId
public String getTransactionId()
Returns the ID string of the current user request transaction.- Throws:
UnsupportedOperationException
- if the transaction ID isn't available in the calling script context- Since:
- 1.0
-
getNextTransactionId
public String getNextTransactionId()
Returns the ID string to be used for the next user request transaction.- Throws:
UnsupportedOperationException
- if the next transaction ID isn't available in the calling script context- Since:
- 1.0
-
getUserInputText
public String getUserInputText()
Returns the user input text. Before flow evaluation starts, this text may be modified by methodsetUserInputText(java.lang.String)
.- Throws:
UnsupportedOperationException
- if the user input text isn't available in the calling script context- Since:
- 1.0
-
setUserInputText
public void setUserInputText(String _sText)
Sets the user input text to be used for flow evaluation.- Throws:
UnsupportedOperationException
- if the user input text isn't writable in the calling script contextIllegalArgumentException
- if the passed parameter value isnull
- Since:
- 1.0
-
getUserInputWords
public String[] getUserInputWords(EngineAccess.WordListType _eWordListType)
Returns the words of the user input text.If an original user input word is split by input processors into multiple final words and the given
EngineAccess.WordListType
isORIGINAL
orSIMPLIFIED
, then the original/simplified word will be stored at the list index of the first word split; at the indices of the following word splits the list will containnull
.- Parameters:
_eWordListType
- selects the type of word list to return, seeEngineAccess.WordListType
(Default:ORIGINAL_PACKED
)- Returns:
- a newly allocated array with the words of the user input, in the same order as in the original text
- Throws:
UnsupportedOperationException
- if the user input words aren't available in the calling script contextIllegalArgumentException
- if the passed parameter value isnull
- Since:
- 1.0
-
getUserInputWords
public String[] getUserInputWords()
Returns the same result as the following method invocation:getUserInputWords(WordListType.ORIGINAL_PACKED)
- Since:
- 1.0
- See Also:
getUserInputWords(WordListType)
-
getUserInputWordCount
@Deprecated public int getUserInputWordCount(EngineAccess.WordListType _eWordListType)
Deprecated.UsegetUserInputWords(EngineAccess.WordListType).length
instead.- Since:
- 1.0
-
getUserInputWordCount
@Deprecated public int getUserInputWordCount()
Deprecated.UsegetUserInputWords().length
instead.- Since:
- 1.0
-
getSentenceCount
public int getSentenceCount()
Returns the number of sentences in the user input.- Throws:
UnsupportedOperationException
- if sentence data aren't available in the calling script context- Since:
- 1.0
-
getSentenceIndex
public int getSentenceIndex()
Returns the index of the user input sentence currently processed or associated with the chosen answer.The first sentence has index
1
.- Throws:
UnsupportedOperationException
- if sentence data aren't available in the calling script context- Since:
- 1.0
-
getSentenceText
public String getSentenceText()
Returns the text of the user input sentence currently processed or associated with the chosen answer.- Throws:
UnsupportedOperationException
- if sentence data aren't available in the calling script context- Since:
- 1.0
-
getSentenceWords
public String[] getSentenceWords(EngineAccess.WordListType _eWordListType)
Returns the words of the user input sentence currently processed or associated with the chosen answer.If an original sentence word is split by input processors into multiple final words and the given
EngineAccess.WordListType
isORIGINAL
orSIMPLIFIED
, then the original/simplified word will be stored at the list index of the first word split; at the indices of the following word splits the list will containnull
.- Parameters:
_eWordListType
- selects the type of word list to return, seeEngineAccess.WordListType
(Default:ORIGINAL_PACKED
).- Returns:
- a newly allocated array with the words of the sentence, in the same order as in the original text
- Throws:
UnsupportedOperationException
- if sentence data aren't available in the calling script contextIllegalArgumentException
- if the passed parameter value isnull
- Since:
- 1.0
-
getSentenceWords
public String[] getSentenceWords()
Returns the same result as the following method invocation:getSentenceWords(WordListType.ORIGINAL_PACKED)
- Since:
- 1.0
- See Also:
getSentenceWords(WordListType)
-
getSentenceWordBeginnings
public List<Integer> getSentenceWordBeginnings(EngineAccess.WordListType _eWordListType)
Returns the beginning character indices of the words of the user input sentence currently processed or associated with the chosen answer.If an original sentence word is split by input processors into multiple final words and the given
EngineAccess.WordListType
isORIGINAL
, then the character index of the begin of the original word will be stored at the list index of the first word split; at the indices of the following word splits the list will containnull
.- Parameters:
_eWordListType
- selects the type of word list to return, seeWordListType
(Default:ORIGINAL_PACKED
). Currently onlyORIGINAL
andORIGINAL_PACKED
are supported.- Returns:
- a newly allocated unmodifiable
List
with the character indices of the word beginnings, in the same order as in the original text - Throws:
UnsupportedOperationException
- if sentence data aren't available in the calling script contextIllegalArgumentException
- if the passed parameter value isnull
- Since:
- 1.3.0
-
getSentenceWordBeginnings
public List<Integer> getSentenceWordBeginnings()
Returns the same result as the following method invocation:getSentenceWordBeginnings(WordListType.ORIGINAL_PACKED)
- Since:
- 1.3.0
- See Also:
getSentenceWordBeginnings(WordListType)
-
getMatchRangeStartIndices
public List<Integer> getMatchRangeStartIndices()
Returns aList
with one or more sentence word indices. The indices point to the location at which the engine will start matching the next part of the current language condition.Multiple indices may be returned in case the current language condition part is tested with candidate search.
The first word of a sentence has index 0. A word index greater than or equal to the count of sentence words indicates that the matching process has reached the end of the sentence.
In order to map a word index to the character position of word beginning in the current sentence text, use method
getSentenceWordBeginnings(WordListType.ORIGINAL)
.- Returns:
- a newly allocated unmodifiable
List
with the word indices - Throws:
UnsupportedOperationException
- if condition test data aren't available in the calling script context- Since:
- 1.3.0
-
getSentenceWordCount
@Deprecated public int getSentenceWordCount(EngineAccess.WordListType _eWordListType)
Deprecated.UsegetSentenceWords(EngineAccess.WordListType).length
instead.- Since:
- 1.0
-
getSentenceWordCount
@Deprecated public int getSentenceWordCount()
Deprecated.UsegetSentenceWords().length
instead.- Since:
- 1.0
-
getThisFlow
public EngineAccess.Data.ActiveFlow getThisFlow()
Returns the flow currently in scope of flow processing. In the scope of a flow trigger the flow associated with the flow trigger is returned. In the scope of flow vertex processing the current flow is returned. Otherwisenull
is returned.Note: Depending on the script context some methods of the returned
ActiveFlow
object may returnnull
.- Since:
- 1.3.0
-
getFlowTriggerOrderGroupValue
public int getFlowTriggerOrderGroupValue(String _sOrderGroupName)
Returns the value of the flow trigger order group with the given name.- Throws:
IllegalArgumentException
- if the flow trigger order group with the given name doesn't exist- Since:
- 1.3.0
-
getTopFlow
public EngineAccess.Data.ActiveFlow getTopFlow()
Returns the topmost element of the active flows stack, ornull
if the stack is empty. The returned flow can either be a normal flow or a subflow (invoked by another flow).- Throws:
UnsupportedOperationException
- if session variable data aren't available in the calling script context- Since:
- 1.3.0
- See Also:
getTopNormalFlow()
-
getTopNormalFlow
public EngineAccess.Data.ActiveFlow getTopNormalFlow()
Returns the topmost normal flow of the active flows stack, ornull
if the stack is empty.- Throws:
UnsupportedOperationException
- if session variable data aren't available in the calling script context- Since:
- 1.3.0
- See Also:
getTopFlow()
-
getProcessingPath
public List<Map<String,Object>> getProcessingPath()
Returns an unmodifiable copy of the vertex processing path for the current turn. The element at index 0 in the returned list is the earliest path element.- Throws:
IllegalStateException
- if flow processing data aren't available in the calling script context- Since:
- 2.1.2
-
getOutputText
public String getOutputText()
Returns the output text of the final response to be returned by the engine.- Throws:
UnsupportedOperationException
- if output data aren't available in the calling script context- Since:
- 1.2.2
-
setOutputText
public void setOutputText(String _sText)
Sets the text of the final response to be returned by the engine.- Throws:
UnsupportedOperationException
- if output data aren't modifiable in the calling script contextIllegalArgumentException
- if the passed parameter value isnull
- Since:
- 1.2.2
-
getOutputEmotion
public String getOutputEmotion()
Returns the output emotion of the final response to be returned by the engine.- Throws:
UnsupportedOperationException
- if output data aren't available in the calling script context- Since:
- 1.2.2
-
setOutputEmotion
public void setOutputEmotion(String _sEmotion)
Sets the emotion of the final response to be returned by the engine.- Throws:
UnsupportedOperationException
- if output data aren't modifiable in the calling script contextIllegalArgumentException
- if the passed parameter value isnull
- Since:
- 1.2.2
-
getOutputURL
public String getOutputURL()
Returns the output URL of the final response to be returned by the engine.- Throws:
UnsupportedOperationException
- if output data aren't available in the calling script context- Since:
- 1.2.2
-
setOutputURL
public void setOutputURL(String _sURL)
Sets the URL of the final response to be returned by the engine.- Throws:
UnsupportedOperationException
- if output data aren't modifiable in the calling script contextIllegalArgumentException
- if the passed parameter value isnull
- Since:
- 1.2.2
-
getUsedRawWords
@Deprecated public String[] getUsedRawWords()
Deprecated.UsegetUsedWords()
.- Since:
- 1.0
-
getUsedWords
public List<String> getUsedWords(EngineAccess.WordListType _eWordListType)
Returns the sentence words used to fulfill a condition. Here 'used' means matches of word conditions with words in the sentence.If an original sentence word is split by input processors into multiple final words and the given
EngineAccess.WordListType
isORIGINAL
orSIMPLIFIED
, then the original/simplified word will be stored at the list index of the first word split if that word is used; for used words at the indices of the following word splits the list will containnull
.- Parameters:
_eWordListType
- selects the type of word list to return, seeEngineAccess.WordListType
(Default:ORIGINAL_PACKED
).- Returns:
- an unmodifiable
List
with the used words, in the selected word form - Throws:
UnsupportedOperationException
- if used words data aren't available in the calling script context- Since:
- 4.0.3
- See Also:
getNotUsedWords(WordListType)
,getSentenceWords(WordListType)
,getUsedWordIndices()
,autoCorrect(java.lang.String)
,simplify(java.lang.String)
,similarWord(java.lang.String)
-
getUsedWords
public List<String> getUsedWords()
Returns the same result as the following method invocation:getUsedWords(WordListType.ORIGINAL_PACKED)
- Returns:
- an unmodifiable
List
with the used words in original form, as given in the user input text - Throws:
UnsupportedOperationException
- if used words data aren't available in the calling script context- Since:
- 4.0.3
- See Also:
getUsedWords(WordListType)
,getNotUsedWords(WordListType)
,getSentenceWords(WordListType)
,getUsedWordIndices()
,autoCorrect(java.lang.String)
,simplify(java.lang.String)
,similarWord(java.lang.String)
-
getUsedRawWordCount
@Deprecated public int getUsedRawWordCount()
Deprecated.- Since:
- 1.0
-
getUsedWordIndices
public SortedSet<Integer> getUsedWordIndices()
Returns the positions of sentence words used to fulfill a condition. Here 'used' means matches of word conditions with words in the sentence.Note: If the returned indices are used to index into the array returned by method
getSentenceWords(EngineAccess.WordListType)
, only usingORIGINAL
,SIMPLIFIED
, andFINAL
for the call togetSentenceWords
will work as expected. UsingORIGINAL_PACKED
orSIMPLIFIED_PACKED
for that call may return a list that doesn't match the list indices returned by this method.- Returns:
- a unmodifiable
SortedSet
of sentence word position indices where the first sentence word has index0
(zero). - Throws:
UnsupportedOperationException
- if used words data aren't available in the calling script context- Since:
- 1.0
- See Also:
getNotUsedWordIndices()
,getSentenceWords(WordListType)
-
getNotUsedRawWords
@Deprecated public String[] getNotUsedRawWords()
Deprecated.UsegetNotUsedWords()
.- Since:
- 1.0
-
getNotUsedWords
public List<String> getNotUsedWords(EngineAccess.WordListType _eWordListType)
Returns the sentence words not used to fulfill a condition. Here 'not used' means mismatches of word conditions with words in the sentence.If an original sentence word is split by input processors into multiple final words and the given
EngineAccess.WordListType
is notFINAL
, then the list will not contain the original/simplified word if any of its word splits are used. Otherwise the original/simplified word will be stored at the list index of the first word split; at the indices of the following word splits the list will containnull
.- Returns:
- an unmodifiable
List
with the not used words, in the selected word form - Throws:
UnsupportedOperationException
- if used words data aren't available in the calling script context- Since:
- 4.0.3
- See Also:
getUsedWords(WordListType)
,getSentenceWords(WordListType)
,getNotUsedWordIndices()
,autoCorrect(java.lang.String)
,simplify(java.lang.String)
,similarWord(java.lang.String)
-
getNotUsedWords
public List<String> getNotUsedWords()
Returns the same result as the following method invocation:getNotUsedWords(WordListType.ORIGINAL_PACKED)
- Returns:
- an unmodifiable
List
with the not used words in original form, as given in the user input text - Throws:
UnsupportedOperationException
- if used words data aren't available in the calling script context- Since:
- 4.0.3
- See Also:
getNotUsedWords(WordListType)
,getUsedWords(WordListType)
,getSentenceWords(WordListType)
,getNotUsedWordIndices()
,autoCorrect(java.lang.String)
,simplify(java.lang.String)
,similarWord(java.lang.String)
-
getNotUsedRawWordCount
@Deprecated public int getNotUsedRawWordCount()
Deprecated.- Since:
- 1.0
-
getNotUsedWordIndices
public SortedSet<Integer> getNotUsedWordIndices()
Returns the positions of the sentence words not used to fulfill a condition. Here 'not used' means mismatches of word conditions with words in the sentence.Note: If the returned indices are used to index into the array returned by method
getSentenceWords(EngineAccess.WordListType)
, only usingORIGINAL
,SIMPLIFIED
, andFINAL
for the call togetSentenceWords
will work as expected. UsingORIGINAL_PACKED
orSIMPLIFIED_PACKED
for that call may return a list that doesn't match the list indices returned by this method.- Returns:
- a unmodifiable
SortedSet
of sentence word position indices where the first sentence word has index0
(zero). - Throws:
UnsupportedOperationException
- if used words data aren't available in the calling script context- Since:
- 1.0
- See Also:
getUsedWordIndices()
,getSentenceWords(WordListType)
-
getLangObjVariable
public String getLangObjVariable(String _sName)
Returns the value of a language object variable with the given name, ornull
if no such language object variable exists.- Parameters:
_sName
- the name of the language object variable- Returns:
- the value of the named language object variable, or
null
if no such language object variable exists - Throws:
UnsupportedOperationException
- if language object variable data aren't available in the calling script contextIllegalArgumentException
- if the passed parameter value isnull
- Since:
- 1.2.1
-
getLangObjVariables
public Map<String,String> getLangObjVariables()
Returns the map of the available language object variables and their values.- Returns:
- an unmodifiable map with the language object variable name as map key and the language object variable value as map value
- Throws:
UnsupportedOperationException
- if language object variable data aren't available in the calling script context- Since:
- 1.2.1
-
setSessVarLifespan
public void setSessVarLifespan(String _sVarName, int _iLifespan)
Sets the lifespan of the specified session variable to the given number of user input turns. The variable will be reset to its default value after the set number of turns, including the current turn.The special lifespan value
LIFESPAN_SESSION
can be used to extend the lifespan until end of the session.A lifespan of
0
(zero) immediately resets the variable to its default value.- Parameters:
_sVarName
- the name of an existing session variable_iLifespan
- the new lifespan, in number of turns (including the current turn)- Throws:
UnsupportedOperationException
- if session variable data aren't available in the calling script contextIllegalArgumentException
- if the variable name parameter isnull
, or the lifespan parameter value is < 0- Since:
- 1.2.0
- See Also:
getSessVarLifespan(java.lang.String)
-
getSessVarLifespan
public int getSessVarLifespan(String _sVarName)
Returns the remaining lifespan of the specified session variable. The returned value is the number of user input turns (including the current turn) after which the variable will be reset to its default value.- Parameters:
_sVarName
- the name of an existing session variable- Returns:
- the remaining lifespan (in number of turns, including the current turn),
or
0
if a session variable with the given name doesn't exist - Throws:
UnsupportedOperationException
- if session variable data aren't available in the calling script contextIllegalArgumentException
- if the variable name parameter isnull
- Since:
- 1.2.0
- See Also:
setSessVarLifespan(java.lang.String, int)
-
getOutputParameter
public String getOutputParameter(String _sName)
Returns the value of an output parameter with the given name, ornull
if no such output parameter exists.- Parameters:
_sName
- the name of the output parameter- Returns:
- the value of the named output parameter, or
null
if no such output parameter exists - Throws:
UnsupportedOperationException
- if output parameter data aren't available in the calling script contextIllegalArgumentException
- if the passed parameter value isnull
- Since:
- 1.0
-
getOutputParameters
public Map<String,String> getOutputParameters()
Returns the map of the available output parameters and their values.- Returns:
- a map with the output parameter name as map key and the output parameter value as map value. Whether the map is modifiable depends on the calling script context
- Throws:
UnsupportedOperationException
- if output parameter data aren't available in the calling script context- Since:
- 1.0
-
putOutputParameter
public void putOutputParameter(String _sName, String _sValue)
Sets the output parameter with the given name and value in the collection of output parameters. If an output parameter with the specified name already exists then it is replaced with the specified new value.- Parameters:
_sName
- the name of the output parameter_sValue
- the value of the output parameter- Throws:
UnsupportedOperationException
- if output parameter data aren't modifiable in the calling script contextIllegalArgumentException
- if a passed parameter value isnull
- Since:
- 1.0
-
autoCorrect
public String autoCorrect(String _sWord)
Returns the auto-corrected version of the given single word, or just the simplified form of the given word if an auto-correction isn't available for it.Whether auto-correction is available depends on the effective input processor(s).
The specified word is converted into its
simplified form
before auto-correction is applied. The (possibly auto-corrected) word is returned in its simplified form.- Throws:
IllegalArgumentException
- if the passed parameter value isnull
- Since:
- 1.0
-
simplify
public String simplify(String _sWord)
Returns the simplified version of a specified text (not necessarily a single word). The text is returned in lower-case.- Throws:
IllegalArgumentException
- if the passed parameter value isnull
- Since:
- 1.0
-
similarWord
public String similarWord(String _sWord)
Searches the internal dictionary for the simplified version of the given word and returns the following result:- the simplified version of the word (in lower case), if it exists in the internal dictionary;
- the alphabetically first of the most similar words from the dictionary, as long as the spelling tolerance threshold isn't exceeded;
- or the
null
object if a sufficiently similar word isn't found.
- Throws:
IllegalArgumentException
- if the passed parameter value isnull
- Since:
- 1.0
-
getActiveFlows
public List<List<EngineAccess.Data.ActiveFlow>> getActiveFlows()
Returns a snapshot of the current active flows stack. The returned object is not updated if the underlying stack data are changed later on by the engine.- Returns:
- a newly allocated and unmodifiable List of List of ActiveFlow items which is decoupled from the internal session data. The outer List contains an entry for each normal flow on the stack. The inner List contains the normal flow as first element, and 0 or more subflows as addition elements (in case the normal flow called subflows). The list element with the highest index is the topmost flow on the stack.
- Throws:
UnsupportedOperationException
- if session data aren't available in the calling script context- Since:
- 1.3.0
-
abortActiveFlow
public void abortActiveFlow(String _sFlowInstanceId)
Marks the flow with the given flow instance ID for premature termination.If this method is called for the current flow (the flow returned by
getThisFlow()
), then the flow will be ended as if it has reached an end node. When the session OnTop script aborts the current flow then the flow's OnTop script is not executed.If this method is called for another flow, then that flow will be ended immediately when it becomes the top flow, or at the end of the current transaction (whatever occurs first). No flow resuming will take place for such a flow (that is, the OnTop scripts are not executed for this flow, and no resume prompt is generated by the flow). Until then the flow remains on the active flow stack, it is not dropped immediately.
All subflows on top of an aborted flow (if any exist) will be aborted as well. Thus, a subflow that calls this method for a (directly or indirectly) calling flow will be aborted as well.
Since an aborted flow is terminating as if it has reached an end node, the OnDrop scripts are then executed in the normal way.
If no active flow with the given ID exists only a warning message is logged.
- Parameters:
_sFlowInstanceId
- the instance ID of the active flow to abort- Throws:
IllegalStateException
- if this operation is not supported in the calling script context- Since:
- 3.0.0
- See Also:
EngineAccess.Data.ActiveFlow.abort()
-
getDialogHistory
public List<EngineAccess.HistoryItem> getDialogHistory()
Returns a snapshot of the session history. The returned object is not updated if the underlying history data are changed later on by the engine.- Returns:
- a unmodifiable List of
EngineAccess.HistoryItem
s - Throws:
UnsupportedOperationException
- if session data aren't available in the calling script context- Since:
- 1.3.0
-
getDialogHistoryLength
public int getDialogHistoryLength()
Returns the number of items in the session history (e.g. the number of dialog steps).- Throws:
UnsupportedOperationException
- if session data aren't available in the calling script context- Since:
- 1.3.0
-
getDialogHistoryUtilities
public EngineAccess.DialogHistoryUtilities getDialogHistoryUtilities()
Returns theEngineAccess.DialogHistoryUtilities
instance which provides convenient methods for dialog history modification.- Returns:
- the mentioned utility class
- Throws:
UnsupportedOperationException
- if the DialogHistoryUtilities instance isn't available in the calling script context- Since:
- 6.2.0
-
putLogVariable
public void putLogVariable(String _sKey, String _sValue)
Puts a key/value pair (a log variable) into the set of log variables to be written to the session log. Only one value can be stored for a particular key. Putting a new value for an already existing key replaces the existing value.When this method is called from a session script, the log variables are buffered until script event 'Post Processing' and are then inserted into the newly created session history entry. Log variables set after that script event are put directly into the last entry of the session history (if one exists).
- Throws:
UnsupportedOperationException
- if log variable data aren't available in the calling script contextIllegalArgumentException
- if a passed parameter value isnull
- Since:
- 1.0
-
setSuppressResumePrompt
public void setSuppressResumePrompt(boolean _bSuppress)
This method is for internal use only.Don't use this method, it might be removed in a future release.
-
divideIntoSentences
public String[] divideIntoSentences(String _sText)
Divides the given text into substrings according to the sentence dividing rules of the engine.- Parameters:
_sText
- the text to split- Returns:
- a newly allocated array with the sentence texts in the same order as in the original text
- Throws:
IllegalArgumentException
- if the passed parameter value isnull
- Since:
- 1.0
-
divideIntoWords
public String[] divideIntoWords(String _sText, EngineAccess.WordListType _eWordListType)
Divides the given text into words according to the word dividing rules of the engine. The text may not contain sentence delimiter characters.- Parameters:
_sText
- the text to split_eWordListType
- selects the type of word list to return, seeEngineAccess.WordListType
(Default:ORIGINAL_PACKED
)- Returns:
- a newly allocated array with the words in the same order as in the original text
- Throws:
IllegalArgumentException
- if a passed parameter value isnull
- Since:
- 1.0
-
divideIntoWords
public String[] divideIntoWords(String _sText)
Returns the same result as the following method invocation:divideIntoWords(_sText, WordListType.ORIGINAL_PACKED)
- Since:
- 1.0
- See Also:
divideIntoWords(String, WordListType)
-
createInputAnnotation
public Annotation createInputAnnotation(String _sName, int _iSentenceIndex, Set<Integer> _zWordIndices, Map<String,Object> _mVariables)
Creates a user inputAnnotation
object with the given data.The created objects is not added to the current annotations. This needs to be done by passing the object to
getInputAnnotations()
.add(...)
- Parameters:
_sName
- the name of the annotation_iSentenceIndex
- the index of the sentence this annotation is assigned to (the first sentence has index 0)_zWordIndices
- the indices of the sentence words this annotation is assigned to (the first word has index 0, the set may be empty)_mVariables
- an arbitrary collection of key/value pairs; ifnull
is passed then an empty map is used- Since:
- 3.1.0
- See Also:
getInputAnnotations()
-
getInputAnnotations
public AnnotationsI getInputAnnotations()
Returns the user input annotations generated by the input processors or added by scripting.Note: The sentence and sentence word indices contained in annotation objects are 0-based, that is, the first sentence / sentence word has index 0.
See method
createInputAnnotation(String, int, Set, Map)
to create new annotation objects.- Since:
- 3.1.0
-
getSentences
public List<SentenceI> getSentences()
Returns an unmodifiable view of the sentences and their words, generated from the user input text.Note: The sentence and sentence word indices contained in annotation objects are 0-based, that is, the first sentence / sentence word has index 0.
- Returns:
- a newly allocated, unmodifiable list of sentences
- Since:
- 3.1.0
-
findMatchingLanguageObjects
@Deprecated public List<EngineAccess.LangCompMatch> findMatchingLanguageObjects(String _sSentenceText, boolean _bUseCurrentSession)
Deprecated.- Since:
- 2.1.0
-
findMatchingLanguageComponents
public List<EngineAccess.LangCompMatch> findMatchingLanguageComponents(String _sSentenceText, boolean _bUseCurrentSession)
Tests all language objects and entities against the given sentence text and returns a list of matches. Language objects excluded from autocoding are not tested. If the sentence text contains more than one sentence then only the first is used.If the current session is used for testing (e.g. in order to provided variables referenced from script conditions in the language object / entity conditions), any variable modifications done by script expressions executed during the matching process are permanent, they are not reverted after the matching is done.
Method
divideIntoWords(String, EngineAccess.WordListType)
may be used to get the sentence words referenced by the used words indices in the match results.- Parameters:
_sSentenceText
- a single sentence_bUseCurrentSession
- iftrue
the current session, otherwise a new session without any variables, is used for the matching process- Returns:
- an unmodifiable
List
with the matching result - Throws:
IllegalArgumentException
- if the give sentence test isnull
IllegalStateException
- if_bUseCurrentSession
istrue
and session data aren't available in the calling script context- Since:
- 2.1.0
- See Also:
divideIntoWords(String, EngineAccess.WordListType)
-
getProperty
public String getProperty(String _sKey, String _sDefault)
Returns the value of a specified property as read from the engine property files. If no such property exists, then the given default value is returned.The Java system properties are accessible through the name expression
systemProperties.
system_property_nameIn the context of the engine web application, the servlet context init parameters and the servlet configuration init parameters are accessible through the name expressions
servletContextParameters.
parameter_name
servletConfigParameters.
parameter_name- Parameters:
_sKey
- the name of the property to fetch_sDefault
- the value to return if the named property doesn't exist; may benull
. (default =""
)- Throws:
IllegalArgumentException
- if a passed parameter value isnull
- Since:
- 1.0
-
getProperty
public String getProperty(String _sKey)
Returns the same result as the following method invocation:getProperty(_sKey, "")
- Since:
- 1.0
-
getEndDialogMetadata
public Map<String,String> getEndDialogMetadata()
Returns an unmodifiable map of the session scope metadata, generated during session termination processing.- Throws:
UnsupportedOperationException
- if session scope metadata aren't available in the calling script context- Since:
- 6.2.0
-
getEndDialogChangedVariables
public Map<String,Object> getEndDialogChangedVariables()
Returns an unmodifiable map of the session scope changed variables, generated during session termination processing.- Throws:
UnsupportedOperationException
- if session scope changed variables aren't available in the calling script context- Since:
- 6.2.0
-
getEndDialogLogVariables
public Map<String,String> getEndDialogLogVariables()
Returns an unmodifiable map of the session scope log variables, generated during session termination processing.- Throws:
UnsupportedOperationException
- if session scope log variables aren't available in the calling script context- Since:
- 6.2.0
-
-