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 to 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: 1.71 $

Copyright © 2005-2006 JVoiceXML group - http://jvoicexml.sourceforge.net/

Author:

Dirk Schnelle

See Also:

Form, VoiceXmlInterpreter

Field Summary

private VoiceXmlInterpreterContext	context The current VoiceXML interpreter context.
private ExecutableForm	form The form to be processed by this FIA.
private Collection<FormItem>	formItems Form items of the current form.
private String	id The id of the form.
private VoiceXmlInterpreter	interpreter The current VoiceXML interpreter.
private static Logger	LOGGER Logger for this class.
private boolean	reprompt true if the last loop iteration ended with a catch that had no <reprompt>.
private TagStrategyFactory	tagstrategyFactory The factory for tag strategies.

Constructor Summary

FormInterpretationAlgorithm(VoiceXmlInterpreterContext ctx, VoiceXmlInterpreter ip, ExecutableForm currentForm)
Construct a new FIA object.

Method Summary

private void	activateGrammars(FormItem item) Activate grammars for the form item.
private EventHandler	collect(FormItem item) Implementation of the collect phase: the selected form item 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).
private void	createShadowVarContainer(FormItem item) Creates a corresponding shadow var container, if the given form item is an InputItem.
void	createVariable(String name, String expr) Creates the var with the given name and a value of the evaluated expression.
void	executeChildNodes(FormItem item) Execute the tag strategies for all child nodes of the given form item.
void	executeChildNodes(FormItem item, NodeList list) Execute the TagStrategy for all nodes of the given list.
void	executeChildNodes(FormItem item, VoiceXmlNode parent) Execute the TagStrategy for all child nodes of the given parent node.
FormItem	getFormItem(String name) Retrieves the form item with the given name.
Collection<FormItem>	getFormItems() Retrieves all form items of the current form.
VoiceXmlInterpreterContext	getVoiceXmlInterpreterContext() Retrieve the current VoiceXmlInterpreterContext.
private void	initFormItem(FormItem item) Initializes the given FormItem
void	initialize() Implementation of the initialization phase.
void	mainLoop() The main loop of the FIA has three phases: The select phase: The next unfilled form item for visiting.
private void	process(FormItem item, EventHandler handler) Implementation of the process phase.
private void	queuePrompt(Prompt prompt) Queue the prompt to the output device.
private void	queuePrompts(PromptCountable countable) Selects the appropriate prompts for an input item or <initial>.
private FormItem	select() Implementation of the select phase: the next unfilled form item is selected for visiting.
private FormItem	select(String name) Select the next form item as a result of a <goto>.
void	setReprompt(boolean on) Set if the last loop iteration ended with a <catch> that had no <reprompt>.
EventHandler	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. A <block> element is visited by setting its form item variable to true, evaluating its content, and then bypassing the process phase.
EventHandler	visitFieldFormItem(FieldFormItem field) If a <field> is visited, the FIA selects and queues up any prompts based on the item'sprompt counter and prompt conditions. If a <field> is visited, the FIA selects and queues up any prompts based on the item'sprompt counter and prompt conditions.
EventHandler	visitInitialFormItem(InitialFormItem initial) This element controls the initial interaction in a mixed initiative form.
EventHandler	visitObjectFormItem(ObjectFormItem ojbect) This input item invokes a platform-specific object with various parameters.
EventHandler	visitRecordFormItem(RecordFormItem record) An input item whose value is an audio clip recorded by the user.
EventHandler	visitSubdialogFormItem(SubdialogFormItem subdialog) A <>subdialog> input item is roughly like a function call.
EventHandler	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

Field Detail

LOGGER

private static final Logger LOGGER

Logger for this class.

form

private final ExecutableForm form

The form to be processed by this FIA.

id

private final String id

The id of the form.

formItems

private Collection<FormItem> formItems

Form items of the current form.

context

private final VoiceXmlInterpreterContext context

The current VoiceXML interpreter context.

interpreter

private final VoiceXmlInterpreter interpreter

The current VoiceXML interpreter.

tagstrategyFactory

private final TagStrategyFactory tagstrategyFactory

The factory for tag strategies.

reprompt

private boolean reprompt

true if the last loop iteration ended with a catch that had no <reprompt>.

Constructor Detail

FormInterpretationAlgorithm

public FormInterpretationAlgorithm(VoiceXmlInterpreterContext ctx,
                                   VoiceXmlInterpreter ip,
                                   ExecutableForm currentForm)

Construct a new FIA object.

Parameters:

ctx - The VoiceXML interpreter context.

ip - The VoiceXML interpreter.

currentForm - The Form to be interpreted.

Method Detail

getVoiceXmlInterpreterContext

public VoiceXmlInterpreterContext getVoiceXmlInterpreterContext()

Retrieve the current VoiceXmlInterpreterContext.

Returns:

The current VoiceXmlInterpreterContext.

initialize

public void initialize()

Implementation of the initialization phase.

Whenever a form is entered, it is initialized. Internal prompt counter variables (in the form's dialog scope) are reset to 1. Each variable (form level <var> elements and form item variable is initialized, in document order, to undefined or to the value of the relevant <expr> attribute.

initFormItem

private void initFormItem(FormItem item)

Initializes the given FormItem

Parameters:

item - The item to initialize.

Since:

0.4

getFormItem

public FormItem getFormItem(String name)

Retrieves the form item with the given name.

Parameters:

name - Name of the form item

Returns:

Corresponding form item, null if it does not exist.

Since:

0.3.1

getFormItems

public Collection<FormItem> getFormItems()

Retrieves all form items of the current form.

Returns:

Collectionof all form items.

Since:

0.3.1

createVariable

public void createVariable(String name,
                           String expr)

Creates the var with the given name and a value of the evaluated expression.

Parameters:

name - Name of the var to create.

expr - Expression to be evaluated.

mainLoop

public void mainLoop()
              throws JVoiceXMLEvent

The main loop of the FIA has three phases:

The select phase: The next unfilled form item for visiting.

The collect phase: the selected form item 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 form items 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 form.

select

private FormItem select()

Implementation of the select phase: the next unfilled form item is selected for visiting.

The purpose of the select phase is to select the next form item to visit. This is done as follows:

If a <goto> from the last main loop iteration's process phase specified a <goto nextitem> then the specified form item is selected.

Otherwise the first form item whose guard condition is false is chosen to be visited. If an error occurs while checking the guard conditions, the event is thrown which skips the collect phase, and is handled in the process phase.

If no guard condition is false, and the last iteration completed the form without encountering an explicit transfer of control, the FIA does an implicit <exit> operation (similarly, if execution proceeds outside of a form, such as when an error is generated outside of a form, and there is no explicit transfer of control, the interpreter will perform an implicit <exit> operation).

Returns:

Next unfilled form item, null if there is none.

select

private FormItem select(String name)

Select the next form item as a result of a <goto>.

Parameters:

name - name of the next form item.

Returns:

Next FormItem, null if there is no form item with that name.

collect

private EventHandler collect(FormItem item)
                      throws JVoiceXMLEvent

Implementation of the collect phase: the selected form item 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 purpose of the collect phase is to collect an input or an event. The selected form item is visited, which performs actions that depend on the type of form item.

Parameters:

item - The form item to visit.

Returns:

The event handler to use for the processing phase.

Throws:

JVoiceXMLEvent - Error or event visiting the form item.

See Also:

select()

process

private void process(FormItem item,
                     EventHandler handler)
              throws JVoiceXMLEvent

Implementation of the process phase. The purpose of the process phase is to process the input or event collected during the previous phases

Parameters:

item - The current form item.

handler - The event handler.

Throws:

JVoiceXMLEvent - Error processing the event.

createShadowVarContainer

private void createShadowVarContainer(FormItem item)
                               throws SemanticError

Creates a corresponding shadow var container, if the given form item is an InputItem.

Parameters:

item - The potential InputItem.

Throws:

SemanticError - Error creating a host object.

See Also:

InputItem

queuePrompts

private void queuePrompts(PromptCountable countable)
                   throws JVoiceXMLEvent

Selects the appropriate prompts for an input item or <initial>. Queue the selected prompts for play prior to the next collect operation.

Parameters:

countable - The prompt countable.

Throws:

JVoiceXMLEvent - Error collecting the prompts or in ptompt evaluation.

queuePrompt

private void queuePrompt(Prompt prompt)
                  throws NoresourceError,
                         BadFetchError

Queue the prompt to the output device.

Parameters:

prompt - The prompt to play back

Throws:

NoresourceError - No output device configured.

BadFetchError - Error evaluating a script within the prompt.

activateGrammars

private void activateGrammars(FormItem item)
                       throws BadFetchError,
                              UnsupportedLanguageError,
                              NoresourceError,
                              UnsupportedFormatError

Activate grammars for the form item.

Parameters:

item - The form item for which the grammars should be activated.

Throws:

BadFetchError - Error retrieving the grammar from the given URI.

UnsupportedLanguageError - The specified language is not supported.

NoresourceError - The input resource is not available.

UnsupportedFormatError - Error in the grammar's format.

visitBlockFormItem

public EventHandler 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 form 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.

Returns:

Event handler for the process phase.

Throws:

JVoiceXMLEvent - Error or event executing the block.

visitFieldFormItem

public EventHandler visitFieldFormItem(FieldFormItem field)
                                throws JVoiceXMLEvent

If a <field> is visited, the FIA selects and queues up any prompts based on the item'sprompt 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'sprompt 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 field form item to visit.

Returns:

Event handler for the process phase.

Throws:

JVoiceXMLEvent - Error or event executing the field.

visitInitialFormItem

public EventHandler 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.

Returns:

Event handler for the process phase.

Throws:

JVoiceXMLEvent - Error or event executing the initial form item.

Stuff to complete

Implement this visitInitialFormItem method.

visitObjectFormItem

public EventHandler visitObjectFormItem(ObjectFormItem ojbect)
                                 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:

ojbect - The object form item to visit.

Returns:

Event handler for the process phase.

Throws:

JVoiceXMLEvent - Error or event executing the object form item.

Stuff to complete

Implement this visitObjectFormItem method.

visitRecordFormItem

public EventHandler 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.

Returns:

Event handler for the process phase.

Throws:

JVoiceXMLEvent - Error or event executing the record form item.

Stuff to complete

Implement this visitRecordFormItem method.

visitSubdialogFormItem

public EventHandler 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.

Returns:

Event handler for the process phase.

Throws:

JVoiceXMLEvent - Error or event executing the subdialog form item.

Stuff to complete

Implement this visitSubdialogFormItem method.

visitTransferFormItem

public EventHandler 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.

Returns:

Event handler for the process phase.

Throws:

JVoiceXMLEvent - Error or event executing the transfer form item.

Stuff to complete

Implement this visitTransferFormItem method.

executeChildNodes

public void executeChildNodes(FormItem item)
                       throws JVoiceXMLEvent

Execute the tag strategies for all child nodes of the given form item.

Parameters:

item - The current form item.

Throws:

JVoiceXMLEvent - Error or event executing the child node.

executeChildNodes

public void executeChildNodes(FormItem item,
                              VoiceXmlNode parent)
                       throws JVoiceXMLEvent

Execute the TagStrategy for all child nodes of the given parent node.

Parameters:

item - The current form item.

parent - The parent node, which is in fact a child to item.

Throws:

JVoiceXMLEvent - Error or event executing the child node.

See Also:

TagStrategy

executeChildNodes

public void executeChildNodes(FormItem item,
                              NodeList list)
                       throws JVoiceXMLEvent

Execute the TagStrategy for all nodes of the given list.

Parameters:

item - The current form item.

list - The list of nodes to execute.

Throws:

JVoiceXMLEvent - Error or event executing the child node.

See Also:

TagStrategy

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 occured that had no reprompt.