org.jvoicexml
Interface UserInput


public interface UserInput

Facade for easy control and monitoring of the user's input.

Objects that implement this interface are able to detect and report character and/or spoken input simultaneously and to control input detection interval duration with a timer whose length is specified by a VoiceXML document.

If an input resource is not available, an error.noresource event must be thrown.

Version:
$Revision: 2800 $
Author:
Dirk Schnelle-Walka

Method Summary
 void activateGrammars(Collection<GrammarDocument> grammars)
          Activates the given grammars.
 void deactivateGrammars(Collection<GrammarDocument> grammars)
          Deactivates the given grammar.
 Collection<BargeInType> getSupportedBargeInTypes()
          Retrieves the barge-in types supported by this UserInput.
 Collection<GrammarType> getSupportedGrammarTypes(ModeType mode)
          Retrieves the grammar types that are supported by this implementation for the given mode.
 GrammarImplementation<?> loadGrammar(Reader reader, GrammarType type)
          Creates a GrammarImplementation from the contents provided by the Reader.
 void startRecognition(SpeechRecognizerProperties speech, DtmfRecognizerProperties dtmf)
          Detects and reports character and/or spoken input simultaneously.
 void stopRecognition()
          Stops a previously started recognition.
 

Method Detail

startRecognition

void startRecognition(SpeechRecognizerProperties speech,
                      DtmfRecognizerProperties dtmf)
                      throws NoresourceError,
                             BadFetchError
Detects and reports character and/or spoken input simultaneously.

Parameters:
speech - the speech recognizer properties to use
dtmf - the DTMF recognizer properties to use
Throws:
NoresourceError - The input resource is not available.
BadFetchError - The active grammar contains some errors.

stopRecognition

void stopRecognition()
Stops a previously started recognition.

See Also:
startRecognition(org.jvoicexml.SpeechRecognizerProperties, org.jvoicexml.DtmfRecognizerProperties)

getSupportedGrammarTypes

Collection<GrammarType> getSupportedGrammarTypes(ModeType mode)
Retrieves the grammar types that are supported by this implementation for the given mode.

It is guaranteed that the implementation is only asked to load grammars via the loadGrammar(Reader, GrammarType) method or activate (activateGrammars(Collection)) and deactivate (deactivateGrammars(Collection)) grammars whos format is returned by this method.

Parameters:
mode - grammar mode
Returns:
supported grammars.
Since:
0.5.5

activateGrammars

void activateGrammars(Collection<GrammarDocument> grammars)
                      throws BadFetchError,
                             UnsupportedLanguageError,
                             NoresourceError,
                             UnsupportedFormatError
Activates the given grammars. It is guaranteed that all grammars types are supported by this implementation. The supported grammar types are retrieved from getSupportedGrammarTypes(ModeType).

GrammarImplementations may be cached. This means that a grammar implementation object is loaded either by this or by another instance of the UserInput. For some implementation platforms it may be necessary that the instance activating the grammar also loaded the grammar. In these cases, the grammar implementation must be loaded in this call. The grammar source may ba accessed by the grammar implementation itself, e.g. SRGS grammar sources can be accessed via SrgsXmlGrammarImplementation.getGrammar().

Parameters:
grammars - Grammars to activate.
Throws:
BadFetchError - Grammar is not known by the recognizer.
UnsupportedLanguageError - The specified language is not supported.
NoresourceError - The input resource is not available.
UnsupportedFormatError - the grammar format is not supported

deactivateGrammars

void deactivateGrammars(Collection<GrammarDocument> grammars)
                        throws NoresourceError,
                               BadFetchError
Deactivates the given grammar. Do nothing if the input resource is not available. It is guaranteed that all grammars types are supported by this implementation.

Parameters:
grammars - Grammars to deactivate.
Throws:
BadFetchError - Grammar is not known by the recognizer.
NoresourceError - The input resource is not available.

loadGrammar

GrammarImplementation<?> loadGrammar(Reader reader,
                                     GrammarType type)
                                     throws NoresourceError,
                                            BadFetchError,
                                            UnsupportedFormatError
Creates a GrammarImplementation from the contents provided by the Reader. If the grammar contained in the Reader already exists, it is over-written.

This method is mainly needed for non SRGS grammars, e.g. JSGF. Loading an SRGS grammar is quite easy and can be implemented e.g. as

final InputSource inputSource = new InputSource(reader);
SrgsXmlDocument doc = new SrgsXmlDocument(inputSource);
// Pass it to the recognizer
return doc;

Parameters:
reader - The Reader from which the grammar text is loaded
type - type of the grammar to read. The type is one of the supported types of the implementation, that has been requested via getSupportedGrammarTypes(ModeType).
Returns:
Read grammar.
Throws:
NoresourceError - The input resource is not available.
BadFetchError - Error reading the grammar.
UnsupportedFormatError - Invalid grammar format.
Since:
0.3

getSupportedBargeInTypes

Collection<BargeInType> getSupportedBargeInTypes()
Retrieves the barge-in types supported by this UserInput.

Returns:
Collection of supported barge-in types, an empty collection, if no types are supported.


Copyright © 2005-2010JVoiceXML group.