FormInterpretationAlgorithm (org.jvoicexml 0.7.8 API)

java.lang.Object
- org.jvoicexml.interpreter.FormInterpretationAlgorithm

All Implemented Interfaces:

FormItemVisitor
```
public final class FormInterpretationAlgorithm
extends java.lang.Object
implements FormItemVisitor
```
Forms are interpreted by an implicit form interpretation algorithm (FIA). The FIA has a main loop that repeatedly selects a form item and then visits it. The selected form item is the first in document order whose guard condition is not satisfied. For instance, a field's default guard condition tests to see if the field's form item variable has a value, so that if a simple form contains only fields, the user will be prompted for each field in turn.
Interpreting a form item generally involves:
- Selecting and playing one or more prompts.
- Collecting a user input, either a response that fills in one ore more input items, or a throwing of some event (help, for instance).
- Interpreting any <filled> action that pertained todo the newly filled in input items.
The FIA ends when it interprets a transfer of control statements (e.g. a <goto> to another dialog or document or a <submit> of data to the document server). It also ends with an implied <exit> when no form item remains eglible to select.
See Also:

Form, Dialog, VoiceXmlInterpreter

Constructor Summary

Constructors
Constructor and Description
`FormInterpretationAlgorithm(VoiceXmlInterpreterContext ctx, VoiceXmlInterpreter ip, Dialog currentDialog)` Construct a new FIA object.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Dialog`	`getDialog()` Retrieves the current dialog.
`FormItem`	`getFormItem()` Retrieves the currently processed `FormItem`.
`FormItem`	`getFormItem(java.lang.String name)` Retrieves the `FormItem` with the given name.
`java.util.Collection<FormItem>`	`getFormItems()` Retrieves all `FormItem`s of the current dialog of the current dialog.
`java.lang.String`	`getLocalProperty(java.lang.String name)` Retrieves the value of the given property.
`TagStrategyExecutor`	`getTagStrategyExecutor()` Retrieves the tag strategy executor.
`VoiceXmlInterpreterContext`	`getVoiceXmlInterpreterContext()` Retrieves the current `VoiceXmlInterpreterContext`.
`void`	`initialize(Profile prof, java.util.Map<java.lang.String,java.lang.Object> parameters)` Implementation of the initialization phase.
`boolean`	`isJustFilled(InputItem input)` Checks, if the `just_filled` flag is set for the given input item.
`boolean`	`isQueuingPrompts()` Checks if the FIA is currently queuing prompts.
`void`	`mainLoop()` The main loop of the FIA has three phases: The select phase: The next unfilled `FormItem` for visiting.
`GrammarDocument`	`processGrammar(org.jvoicexml.xml.srgs.Grammar grammar)` Processes the given grammar tag and adds it to the `ActiveGrammarSet`.
`void`	`setJustFilled(InputItem input)` Sets the `just_filled` flag for the given input item.
`void`	`setLocalProperty(java.lang.String name, java.lang.String value)` Sets the property with the given name to the given value.
`void`	`setReprompt(boolean on)` Set if the last loop iteration ended with a `<catch>` that had no `<reprompt>`.
`void`	`visitBlockFormItem(BlockFormItem block)` A `<block>` element is visited by setting its form item variable to `true`, evaluating its content, and then bypassing the process phase.
`void`	`visitFieldFormItem(InputItem field)` If a `<field>` is visited, the FIA selects and queues up any prompts based on the item's prompt counter and prompt conditions.
`void`	`visitInitialFormItem(InitialFormItem initial)` This element controls the initial interaction in a mixed initiative form.
`void`	`visitObjectFormItem(ObjectFormItem object)` This input item invokes a platform-specific object with various parameters.
`void`	`visitRecordFormItem(RecordFormItem record)` An input item whose value is an audio clip recorded by the user.
`void`	`visitSubdialogFormItem(SubdialogFormItem subdialog)` A `<subdialog>` input item is roughly like a function call.
`void`	`visitTransferFormItem(TransferFormItem transfer)` An input item which transfers the user to another telephone number.

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

- Constructor Detail
  - FormInterpretationAlgorithm
```
public FormInterpretationAlgorithm(VoiceXmlInterpreterContext ctx,
                                   VoiceXmlInterpreter ip,
                                   Dialog currentDialog)
```
    Construct a new FIA object.
    
    Parameters:
    
    ctx - the VoiceXML interpreter context.
    
    ip - the VoiceXML interpreter.
    
    currentDialog - the dialog to be interpreted.
- Method Detail
  - getDialog
```
public Dialog getDialog()
```
    Retrieves the current dialog.
    
    Returns:
    
    the current dialog.
  - getVoiceXmlInterpreterContext
```
public VoiceXmlInterpreterContext getVoiceXmlInterpreterContext()
```
    Retrieves the current VoiceXmlInterpreterContext.
    
    Returns:
    
    The current VoiceXmlInterpreterContext.
  - getTagStrategyExecutor
```
public TagStrategyExecutor getTagStrategyExecutor()
```
    Retrieves the tag strategy executor.
    
    Returns:
    
    the tag strategy executor.
    
    Since:
    
    0.7
  - initialize
```
public void initialize(Profile prof,
                       java.util.Map<java.lang.String,java.lang.Object> parameters)
                throws JVoiceXMLEvent
```
    Implementation of the initialization phase.
    Whenever a dialog is entered, it is initialized. Internal prompt counter variables (in the dialog's dialog scope) are reset to 1. Each variable (form level <var> elements and FormItem variable is initialized, in document order, to undefined or to the value of the relevant <expr> attribute.
    
    Parameters:
    
    prof - the profile
    
    parameters - passed parameters when executing this dialog
    
    Throws:
    
    JVoiceXMLEvent - Error initializing the FormItems.
  - getFormItem
```
public FormItem getFormItem(java.lang.String name)
```
    Retrieves the FormItem with the given name.
    
    Parameters:
    
    name - Name of the FormItem
    
    Returns:
    
    Corresponding FormItem, null if it does not exist.
    
    Since:
    
    0.3.1
  - getFormItems
```
public java.util.Collection<FormItem> getFormItems()
```
    Retrieves all FormItems of the current dialog of the current dialog.
    
    Returns:
    
    Collection of all FormItems.
    
    Since:
    
    0.3.1
  - getFormItem
```
public FormItem getFormItem()
```
    Retrieves the currently processed FormItem.
    
    Returns:
    
    the current form item.
    
    Since:
    
    0.7
  - mainLoop
```
public void mainLoop()
              throws JVoiceXMLEvent
```
    The main loop of the FIA has three phases:
    The select phase: The next unfilled FormItem for visiting.
    
    The collect phase: the selected FormItem is visited, which prompts the user for input, enables the appropriate grammars, and then waits for and collects an input (such as a spoken phrase or DTMF key presses) or an event (such as a request for help or a no input timeout.
    
    The process phase: an input is processed by filling FormItems and executing <var> elements to perform input validation. An event is processed by executing the appropriate event handler for that event type.
    
    Throws:
    
    JVoiceXMLEvent - Error or event processing the dialog.
  - setJustFilled
```
public void setJustFilled(InputItem input)
```
    Sets the just_filled flag for the given input item.
    
    Parameters:
    
    input - the input item.
    
    Since:
    
    0.5.1
  - isJustFilled
```
public boolean isJustFilled(InputItem input)
```
    Checks, if the just_filled flag is set for the given input item.
    
    Parameters:
    
    input - the input item
    
    Returns:
    
    true if the flag is set.
    
    Since:
    
    0.7
  - isQueuingPrompts
```
public boolean isQueuingPrompts()
```
    Checks if the FIA is currently queuing prompts. The behaviour of the TagStrategys might be different dependent on the queuing mode.
    
    Returns:
    
    true if the FIA is currently queiung prompts.
  - processGrammar
```
public GrammarDocument processGrammar(org.jvoicexml.xml.srgs.Grammar grammar)
                               throws UnsupportedFormatError,
                                      NoresourceError,
                                      BadFetchError,
                                      SemanticError
```
    Processes the given grammar tag and adds it to the ActiveGrammarSet.
    
    Parameters:
    
    grammar - grammar to process.
    
    Returns:
    
    the processed grammar.
    
    Throws:
    
    NoresourceError - Error accessing the input device.
    
    UnsupportedFormatError - If an unsupported grammar has to be processed.
    
    BadFetchError - If the document could not be fetched successfully.
    
    SemanticError - if there was an error evaluating a scripting expression
  - visitBlockFormItem
```
public void visitBlockFormItem(BlockFormItem block)
                        throws JVoiceXMLEvent
```
    A <block> element is visited by setting its form item variable to true, evaluating its content, and then bypassing the process phase. No input is collected, and the next iteration of the FIA's main loop is entered. A <block> element is visited by setting its dialog item variable to true, evaluating its content, and then bypassing the process phase.
    
    Specified by:
    
    visitBlockFormItem in interface FormItemVisitor
    
    Parameters:
    
    block - The block form item to visit.
    
    Throws:
    
    JVoiceXMLEvent - Error or event executing the block.
  - visitFieldFormItem
```
public void visitFieldFormItem(InputItem field)
                        throws JVoiceXMLEvent
```
    If a <field> is visited, the FIA selects and queues up any prompts based on the item's prompt counter and prompt conditions. Then it activates and listens for the field level grammar(s) and any higher-level grammars, and waits for the item to be filled or for some events to be generated. If a <field> is visited, the FIA selects and queues up any prompts based on the item's prompt counter and prompt conditions. Then it activates and listens for the field level grammar(s) and any higher-level grammars, and waits for the item to be filled or for some events to be generated.
    
    Specified by:
    
    visitFieldFormItem in interface FormItemVisitor
    
    Parameters:
    
    field - the input form item to visit.
    
    Throws:
    
    JVoiceXMLEvent - Error or event executing the field.
  - visitInitialFormItem
```
public void visitInitialFormItem(InitialFormItem initial)
                          throws JVoiceXMLEvent
```
    This element controls the initial interaction in a mixed initiative form. Its prompts should be written to encourage the user to say something matching a form level grammar. When at least one input item variable is filled as a result of recognition during an <initial> element, the form item variable of <initial> becomes true, thus removing it as an alternative for the FIA.
    
    Specified by:
    
    visitInitialFormItem in interface FormItemVisitor
    
    Parameters:
    
    initial - The field form item to visit.
    
    Throws:
    
    JVoiceXMLEvent - Error or event executing the initial form item.
  - visitObjectFormItem
```
public void visitObjectFormItem(ObjectFormItem object)
                         throws JVoiceXMLEvent
```
    This input item invokes a platform-specific object with various parameters. The result of the platform object is an ECMAScript Object. One platform object could be a builtin dialog that gathers credit card information. Another could gather a text message using some proprietary DTMF text entry method. There is no requirement for implementations to provide platform-specific objects, although implementations must handle the <object> element by throwing error.unsupported.objectname if the particular platform-specific object is not supported (note that objectname in error.unsupported.objectname is a fixed string, so not substituted with the name of the unsupported object; more specific error information may be provided in the event _message special variable as described in Section 5.2.2).
    
    Specified by:
    
    visitObjectFormItem in interface FormItemVisitor
    
    Parameters:
    
    object - The object form item to visit.
    
    Throws:
    
    JVoiceXMLEvent - Error or event executing the object form item.
  - visitRecordFormItem
```
public void visitRecordFormItem(RecordFormItem record)
                         throws JVoiceXMLEvent
```
    An input item whose value is an audio clip recorded by the user. A <record> element could collect a voice mail message, for instance.
    
    Specified by:
    
    visitRecordFormItem in interface FormItemVisitor
    
    Parameters:
    
    record - The record form item to visit.
    
    Throws:
    
    JVoiceXMLEvent - Error or event executing the record form item.
  - visitSubdialogFormItem
```
public void visitSubdialogFormItem(SubdialogFormItem subdialog)
                            throws JVoiceXMLEvent
```
    A <subdialog> input item is roughly like a function call. It invokes another dialog on the current page, or invokes another VoiceXML document. It returns an ECMAScript Object as its result.
    
    Specified by:
    
    visitSubdialogFormItem in interface FormItemVisitor
    
    Parameters:
    
    subdialog - The subdialog form item to visit.
    
    Throws:
    
    JVoiceXMLEvent - Error or event executing the subdialog form item.
  - visitTransferFormItem
```
public void visitTransferFormItem(TransferFormItem transfer)
                           throws JVoiceXMLEvent
```
    An input item which transfers the user to another telephone number. If the transfer returns control, the field variable will be set to the result status.
    
    Specified by:
    
    visitTransferFormItem in interface FormItemVisitor
    
    Parameters:
    
    transfer - The transfer form item to visit.
    
    Throws:
    
    JVoiceXMLEvent - Error or event executing the transfer form item.
  - setReprompt
```
public void setReprompt(boolean on)
```
    Set if the last loop iteration ended with a <catch> that had no <reprompt>.
    
    Parameters:
    
    on - true if a catch occurred that had no reprompt.
  - getLocalProperty
```
public java.lang.String getLocalProperty(java.lang.String name)
```
    Retrieves the value of the given property.
    
    Parameters:
    
    name - Name of the property.
    
    Returns:
    
    Value of the property.
    
    Since:
    
    0.7.5
  - setLocalProperty
```
public void setLocalProperty(java.lang.String name,
                             java.lang.String value)
```
    Sets the property with the given name to the given value.
    
    Parameters:
    
    name - Name of the property.
    
    value - Value of the property.
    
    Since:
    
    0.7.5

Class FormInterpretationAlgorithm

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

FormInterpretationAlgorithm

Method Detail

getDialog

getVoiceXmlInterpreterContext

getTagStrategyExecutor

initialize

getFormItem

getFormItems

getFormItem

mainLoop

setJustFilled

isJustFilled

isQueuingPrompts

processGrammar

visitBlockFormItem

visitFieldFormItem

visitInitialFormItem

visitObjectFormItem

visitRecordFormItem

visitSubdialogFormItem

visitTransferFormItem

setReprompt

getLocalProperty

setLocalProperty