Package com.artisol.teneo.engine.core.engine

Class 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.6.0

    • 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

      • 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 context
        IllegalArgumentException - if the passed parameter value is null
        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 is ORIGINAL or SIMPLIFIED, 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 contain null.

        Parameters:
        _eWordListType - selects the type of word list to return, see EngineAccess.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 context
        IllegalArgumentException - if the passed parameter value is null
        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)

      • 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 is ORIGINAL or SIMPLIFIED, 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 contain null.

        Parameters:
        _eWordListType - selects the type of word list to return, see EngineAccess.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 context
        IllegalArgumentException - if the passed parameter value is null
        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 is ORIGINAL, 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 contain null.

        Parameters:
        _eWordListType - selects the type of word list to return, seeWordListType (Default: ORIGINAL_PACKED). Currently only ORIGINAL and ORIGINAL_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 context
        IllegalArgumentException - if the passed parameter value is null
        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 a List 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

      • 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. Otherwise null is returned.

        Note: Depending on the script context some methods of the returned ActiveFlow object may return null.

        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, or null 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()

      • 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 context
        IllegalArgumentException - if the passed parameter value is null
        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 context
        IllegalArgumentException - if the passed parameter value is null
        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 context
        IllegalArgumentException - if the passed parameter value is null
        Since:
        1.2.2

      • getLangObjVariable

        public String getLangObjVariable​(String _sName)
        Returns the value of a language object variable with the given name, or null 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 context
        IllegalArgumentException - if the passed parameter value is null
        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 context
        IllegalArgumentException - if the variable name parameter is null, 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 context
        IllegalArgumentException - if the variable name parameter is null
        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, or null 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 context
        IllegalArgumentException - if the passed parameter value is null
        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 context
        IllegalArgumentException - if a passed parameter value is null
        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 is null
        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 is null
        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 is null
        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()

      • 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

      • 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 context
        IllegalArgumentException - if a passed parameter value is null
        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 is null
        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, see EngineAccess.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 is null
        Since:
        1.0

      • createInputAnnotation

        public Annotation createInputAnnotation​(String _sName,
                                        int _iSentenceIndex,
                                        Set<Integer> _zWordIndices,
                                        Map<String,​Object> _mVariables)
        Creates a user input Annotation 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; if null 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

      • 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 - if true 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 is null
        IllegalStateException - if _bUseCurrentSession is true 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_name

        In 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 be null. (default = "")
        Throws:
        IllegalArgumentException - if a passed parameter value is null
        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