org.jvoicexml.interpreter
Class FormInterpretationAlgorithm

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

All Implemented Interfaces:

FormItemVisitor

public final class FormInterpretationAlgorithm
extends 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.

Version:

$Revision: 2913 $

Author:

Dirk Schnelle-Walka

See Also:

Form, Dialog, VoiceXmlInterpreter

Constructor Summary

FormInterpretationAlgorithm(VoiceXmlInterpreterContext ctx, VoiceXmlInterpreter ip, Dialog currentDialog)
Construct a new FIA object.

Method Summary

Dialog	getDialog() Retrieves the current dialog.
FormItem	getFormItem() Retrieves the currently processed FormItem.
FormItem	getFormItem(String name) Retrieves the FormItem with the given name.
Collection<FormItem>	getFormItems() Retrieves all FormItems of the current dialog of the current dialog.
String	getLocalProperty(String name) Retrieves the value of the given property.
TagStrategyExecutor	getTagStrategyExecutor() Retrieves the tag strategy executor.
VoiceXmlInterpreterContext	getVoiceXmlInterpreterContext() Retrieves the current VoiceXmlInterpreterContext.
void	initialize(InitializationTagStrategyFactory factory) 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(Grammar grammar) Process the given grammar tags and add them to the ActiveGrammarSet.
void	setJustFilled(InputItem input) Sets the just_filled flag for the given input item.
void	setLocalProperty(String name, 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(InitializationTagStrategyFactory factory)
                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:

factory - the tag initialization tag factory

Throws:

JVoiceXMLEvent - Error initializing the FormItems.

getFormItem

public FormItem getFormItem(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 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(Grammar grammar)
                               throws UnsupportedFormatError,
                                      NoresourceError,
                                      BadFetchError,
                                      SemanticError

Process the given grammar tags and add them 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.

Stuff to complete

Implement this visitSubdialogFormItem method.

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.

Stuff to complete

Implement bridge transfer., Have to send event "connection.disconnect.transfer"

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 String getLocalProperty(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(String name,
                             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