Interface javax.speech.recognition.Recognizer


Overview \| Package \| Class \| Tree \| Index \| Help
PREV CLASS \| NEXT CLASS	FRAMES \| NO FRAMES
SUMMARY: INNER \| FIELD \| CONSTR \| METHOD	DETAIL: FIELD \| CONSTR \| METHOD

Interface javax.speech.recognition.Recognizer

public abstract interface Recognizer
extends Engine

A Recognizer provides access to speech recognition capabilities. The Recognizer interface extends the javax.speech.Engine interface and so inherits the basic engine capabilities and provides additional specialized capabilities.

The primary capabilities provided by a recognizer are grammar management and result handling. An application is responsible for providing a recognizer with grammars. A Grammar defines a set of words (technically known as tokens) and defines patterns in which the tokens may be spoken. When a grammar is active the recognizer listens for speech in the incoming audio which matches the grammar. When speech is detected the recognizer produces a Result. The result object is passed to the application and contains information on which words were heard.

The types of grammars, mechanisms for creating, modifying and managing grammars, types of results, result handling and other recognizer functions are described in more detail below.

Creating a Recognizer

A Recognizer is created by a call to createRecognizer method of the Central class. Detailed descriptions of the procedures for locating, selecting, creating and initializing a Recognizer are provided in the documentation for Central.

Inherited and Extended Engine Capabilities

The Recognizer interface and the other classes and interfaces of the javax.speech.recognition package extend and modify the basic engine capabilities in the following ways.

Inherits engine location by Central.availableRecognizers method and EngineModeDesc.
Extends EngineModeDesc as RecognizerModeDesc.
Inherits allocate and deallocate methods from Engine.
Inherits pause and resume methods from Engine.
Inherits the getEngineState, waitEngineState and testEngineState methods from the Engine interface for handling engine state.
Inherits the DEALLOCATED, ALLOCATED, ALLOCATING_RESOURCES and DEALLOCATING_RESOURCES states from the Engine interface.
Inherits the PAUSED and RESUMED sub-states of the ALLOCATED state.
Adds PROCESSING, LISTENING and SUSPENDED sub-states of the ALLOCATED state.
Adds FOCUS_ON and FOCUS_OFF sub-states of the ALLOCATED state.
Adds requestFocus and releaseFocus methods for managing an application's speech focus.
Adds special suspend and commit mechanisms for updating definitions and enabling of grammars: suspend, commitChanges.
Inherits audio management: see Engine.getAudioManager and AudioManager.
Inherits the Engine.getEngineProperties method adds the getRecognizerProperties so that a cast is not required.
Extends audio event mechanism: see RecognizerAudioListener and RecognizerAudioEvent.
Inherits vocabulary management: see Engine.getVocabManager and VocabManager.
Inherits addEngineListener and removeEngineListener methods from the Engine interface.
Extends EngineListener interface as RecognizerListener.
Adds grammar management of Grammar, RuleGrammar, DictationGrammar GrammarEvent, and GrammarListener,
Adds recognition result mechanisms through Result, FinalResult, FinalRuleResult, FinalDictationResult, ResultListener and ResultEvent.

Grammars

The creation, modification, enabling, activation and other management of grammars is a core function provided by any recognizer. A recognizer must be provided with one or more grammars that indicate what words and word sequences it should listen for. The basic process for dealing with a grammar are:

Create a new Grammar or obtain a reference to an existing grammar.
Attach a ResultListener to either the Recognizer or Grammar to get Result events.
As necessary, setup or modify the grammar according to the application context.
Enable and disable the Grammar for recognition as required.
Commit changes to grammar definition and enabled status.
Repeat steps 1 through 5 as required.
Delete application-created grammars when they are no longer needed.

Each grammar must be identified by a unique grammar name which is defined when the Grammar is created. The following methods deal with grammar names:

Grammar.getName returns the name of a Grammar object.
getRuleGrammar returns a reference to a Grammar given the grammar's names.

A Recognizer provides several methods for the creation and loading of RuleGrammars:

newRuleGrammar: create a RuleGrammar from scratch
loadJSGF: create a RuleGrammar(s) from Java Speech Grammar Format text obtained from either a Reader or a URL. The advanced loadJSGF method provides additional load controls.
readVendorGrammar: read a grammar stored in a vendor-specific (non-portable) format.

Other important rule grammar functions are:

deleteRuleGrammar deletes a loaded grammar.
listRuleGrammars returns an array of references to all grammars loaded into a Recognizer.
RuleGrammar.toString produces a string representing a RuleGrammar in Java Speech Grammar Format.
writeVendorGrammar: write a grammar in a vendor-specific (non-portable) format.

In addition to RuleGrammars that an application creates, some recognizers have "built-in" grammars. A built-in grammar is automatically loaded into the recognizer when the recognizer is created and are accessible through the listRuleGrammars method. Different recognizers will have different built-in grammars so applications should not rely upon built-in grammars if they need to be portable.

A DictationGrammar is the most important kind of built-in grammar. A dictation grammar supports relatively free-form input of text. If a recognizer supports dictation, then the getDictationGrammar method returns non-null and the isDictationGrammarSupported method of the RecognizerModeDesc returns true.

Grammar Scope

Each Recognizer object has a separate name-space. Applications should be aware that changes to a Grammar object affect any part of the application that uses that Grammar. However, if two separate applications create a Recognizer and use a Grammar with the same name, they are effectively independent - changes by on app do not affect the operation of the other app.

Efficiency

The processing of grammars (particularly large grammars) can be computationally expensive. Loading a new grammar can take seconds or sometimes minutes. Updates to a Grammar may also be slow. Therefore, applications should take precautions to build grammars in advance and to modify them only when necessary. Furthermore, an application should minimize the number of grammars active at any point in time.

Recognizer States

A Recognizer inherits the PAUSED and RESUMED sub-states of the ALLOCATED from the Engine interface. The Recognizer interface adds two more independent sub-states systems to the ALLOCATED state:

LISTENING, PROCESSING, SUSPENDED
FOCUS_ON, FOCUS_OFF

Recognizer States: Focus

A Recognizer adds the two state sub-state-system for FOCUS_ON and FOCUS_OFF to indicate whether this instance of the Recognizer currently has the speech focus. Focus is important in a multi-application environment because more than one application can connect to an underlying speech recognition engine, but the user gives speech focus to only one application at a time. Since it is normal for an application to use only one Recognizer, Recognizer focus and application focus normally mean the same thing. (Multi-recognizer apps cannot make this assumption.)

Focus is not usually relevant in telephony applications in which there is a single input audio stream to a single application.

The focus status is a key factor in determining the activation of grammars and therefore in determining when results will and will not be generated. The activation conditions for grammars and the role of focus are described in the documentation for the Grammar interface.

When recognizer focus is received a FOCUS_GAINED event is issued to RecognizerListeners. When recognizer focus is released or otherwise lost, a FOCUS_LOST event is issued to RecognizerListeners.

Applications can request speech focus for the Recognizer by calling the requestFocus mechanism. This asynchronous method may return before focus in received. To determine when focus is on, check for FOCUS_GAINED events or test the FOCUS_ON bit of engine state.

Applications can release speech focus from the Recognizer by calling the releaseFocus mechanism. This asynchronous method may return before focus in lost. To determine whether focus is off, check for FOCUS_LOST events or test the FOCUS_OFF bit of engine state.

In desktop environments, it is normal (but not a requirement) for speech focus to follow window focus. Therefore, it is common for the requestFocus method to be called on AWT events or Swing events such as FocusEvent and WindowEvent.

A well-behaved application only requests focus when it knows that it has the speech focus of the user (the user is talking to it and not to other applications). A well-behaved application will also release focus as soon as it finishes with it.

Recognizer States: Result Recognition

A Recognizer adds the three state sub-state-system for LISTENING, PROCESSING and SUSPENDED to indicate the status of the recognition of incoming speech. These three states are loosely coupled with the PAUSED and RESUMED states but only to the extent that turning on and off audio input will affect the recognition process. An ALLOCATED recognizer is always in one of these three states:

LISTENING state: the Recognizer is listening to incoming audio for speech that may match an active grammar but has not detected speech yet.
PROCESSING state: the Recognizer is processing incoming speech that may match an active grammar to produce a result.
SUSPENDED state: the Recognizer is temporarily suspended while grammars are updated. While suspended, audio input is buffered for processing once the recognizer returns to the LISTENING and PROCESSING states.

Recognizer States: Result Recognition: Typical Event Cycle

The typical state cycle is as follows.

A Recognizer starts in the LISTENING state with a certain set of grammars enabled. When incoming audio is detected that may match an active grammar, the Recognizer transitions to the PROCESSING state with a RECOGNIZER_PROCESSING RecognizerEvent. The Recognizer then creates a new Result and issues a RESULT_CREATED event to provide it to the application.
The Recognizer remains in the PROCESSING state until it completes recognition of the result.
The recognizer indicates completion of recognition by issuing a RECOGNIZER_SUSPENDED RecognizerEvent to transition from the PROCESSING state to the SUSPENDED state. Once in that state, it issues a result finalization event to ResultListeners (RESULT_ACCEPTED or RESULT_REJECTED event).
The Recognizer remains in the SUSPENDED state until processing of the result finalization event is completed. Applications will usually make any necessary grammar changes while the recognizer is SUSPENDED. In this state the Recognizer buffers incoming audio. This buffering allows a user to continue speaking without speech data being lost. Once the Recognizer returns to the LISTENING state the buffered audio is processed to give the user the perception of real-time processing.
The Recognizer commits all grammar changes, issues a CHANGES_COMMITTED event to RecognizerListeners to return to the LISTENING state. It also issues GRAMMAR_CHANGES_COMMITTED events to GrammarListeners of changed grammars. The commit applies all grammar changes made at any point up to the end of result finalization, typically including changes made in the result finalization events.
The Recognizer is back in the LISTENING state listening for speech that matches the new grammars.

In this state cycle, the RECOGNIZER_PROCESSING and RECOGNIZER_SUSPENDED events are triggered by user actions: starting and stopping speaking. The third state transition -- CHANGES_COMMITTED -- is triggered programmatically some time after the RECOGNIZER_SUSPENDED event.

Recognizer States: Result Recognition: Non-Speech Events

For applications that deal only with spoken input the state cycle above handles most normal speech interactions. For applications that handle other asynchronous input, additional state transitions are possible. Other types of asynchronous input include graphical user interface events (e.g., AWTEvents), timer events, multi-threading events, socket events and much more.

When a non-speech event occurs which changes the application state or applicatin data it is often necessary to update the recognizer's grammars. Furthermore, it is typically necessary to do this as if the change occurred in real time - at exactly the point in time at which the event occurred.

The suspend and commitChanges methods of a Recognizer are used to handle non-speech asynchronous events. The typical cycle for updating grammars is as follows:

Assume that the Recognizer is in the LISTENING state (the user is not currently speaking). As soon as the event is received, the application calls suspend to indicate that it is about to change grammars.
The recognizer issues a RECOGNIZER_SUSPENDED event and transitions from the LISTENING state to the SUSPENDED state.
The application makes all necessary changes to the grammars.
Once all changes are completed the application calls the commitChanges method. The recognizer applies the new grammars, issues a CHANGES_COMMITTED event to transition from the SUSPENDED state back to the LISTENING, and issues GRAMMAR_CHANGES_COMMITTED events to all changed grammars.
The Recognizer resumes recognition of the buffered audio and then live audio with the new grammars.

Because audio is buffered from the time of the asynchronous event to the time at which the CHANGES_COMMITTED occurs, the audio is processed as if the new grammars were applied exactly at the time of the asynchronous event. The user has the perception of real-time processing.

Although audio is buffered in the SUSPENDED state, applications should makes changes and commitChanges as quickly as possible. This minimizes the possibility of a buffer overrun. It also reduces delays in recognizing speech and responding to the user.

Note: an application is not technically required to call suspend prior to calling commitChanges. If the suspend call is ommitted the Recognizer behaves as if suspend had been called immediately prior to calling commitChanges. An application that does not call suspend risks a commit occurring unexpectedly and leaving grammars in an inconsistent state.

Recognizer States: Result Recognition: Mixing Speech and Non-Speech Events

There is no guarantee that a speech and non-speech events will not be mixed. If a speech event occurs in the absence of non-speech events, the normal event cycle takes place. If a non-speech event occurs in the absence of any speech events, the non-speech event cycle takes place.

We need to consider two cases in which speech and non-speech events interact: (1) when a non-speech event occurs during the processing of a speech event, and (2) when a speech event occurs during the processing of a non-speech event.

Non-speech event occurs during processing of a speech event:
Technically, this is the case in which a non-speech event is issued while the Recognizer is in either the PROCESSING state or the SUSPENDED state. In both cases the event processing for the non-speech is no different than normal. The non-speech event handler calls suspend to indicate it is about to change grammars, makes the grammar changes, and then calls commitChanges to apply the changes.
The effect is that the CHANGES_COMMITTED event that would normally occur in the normal event cycle may be delayed until the commitChanges method is explicitly called and that the commit applies changes made in response to both the speech and non-speech events. If the commitChanges call for the non-speech event is made before the end of the result finalization event, there is no delay of the CHANGES_COMMITTED event.
Speech event occurs during processing of a non-speech event:
This case is simpler. If the user starts speaking while a non-speech event is being processed, then the Recognizer is in the SUSPENDED state, that speech is buffered, and the speech event is actually delayed until the Recognizer returns to the LISTENING state. Once the Recognizer returns to the LISTENING state, the incoming speech is processed with the normal event cycle.

See Also:: RecognizerEvent, EngineListener, RecognizerListener, Grammar, RuleGrammar, DictationGrammar, Result, FinalResult

Field Summary
static long	FOCUS_OFF `FOCUS_OFF` is the bit of state that is set when an `ALLOCATED` `Recognizer` does not have the speech focus of the underlying speech recognition engine.
static long	FOCUS_ON `FOCUS_ON` is the bit of state that is set when an `ALLOCATED` `Recognizer` has the speech focus of the underlying speech recognition engine.
static long	LISTENING `LISTENING` is the bit of state that is set when an `ALLOCATED` `Recognizer` is listening to incoming audio for speech that may match an active grammar but has not yet detected speech.
static long	PROCESSING `PROCESSING` is the bit of state that is set when an `ALLOCATED` `Recognizer` is producing a `Result` for incoming speech that may match an active grammar.
static long	SUSPENDED `SUSPENDED` is the bit of state that is set when an `ALLOCATED` `Recognizer` is temporarily suspended while grammar definition and grammar enabled settings are updated.

Method Summary
void	addResultListener(ResultListener listener) Request notifications of all events for all `Result` produced by this `Recognizer`.
void	commitChanges() Commit changes to all loaded grammars and all changes of grammar enabling since the last `commitChanges`.
void	deleteRuleGrammar(RuleGrammar grammar) Delete a `RuleGrammar` from the `Recognizer`.
void	forceFinalize(boolean flush) If the `Recognizer` is in the `PROCESSING` state (producing a `Result`), force the `Recognizer` to immediately complete processing of that result by finalizing it.
DictationGrammar	getDictationGrammar(String name) Return the `DictationGrammar` for a `Recognizer`.
RecognizerProperties	getRecognizerProperties() Return the `RecognizerProperties` object (a JavaBean).
RuleGrammar	getRuleGrammar(String name) Get the `RuleGrammar` with the specified name.
SpeakerManager	getSpeakerManager() Return an object which provides management of the speakers of a `Recognizer`.
RuleGrammar[]	listRuleGrammars() List the `RuleGrammars` known to the `Recognizer`.
RuleGrammar	loadJSGF(Reader JSGF) Create a `RuleGrammar` from Java Speech Grammar Format text provided by the `Reader`.
RuleGrammar	loadJSGF(URL context, String grammarName) Load a `RuleGrammar` and its imported grammars from Java Speech Grammar Format text from URLs or from system resources.
RuleGrammar	loadJSGF(URL context, String grammarName, boolean loadImports, boolean reloadGrammars, Vector loadedGrammars) Load a `RuleGrammar` in Java Speech Grammar Format text from a URL or from system resources and optionally load its imports.
RuleGrammar	newRuleGrammar(String name) Create a new `RuleGrammar` for this recognizer with a specified grammar name.
Grammar	readVendorGrammar(InputStream input) Create a new grammar by reading in a grammar stored in a vendor-specific format.
Result	readVendorResult(InputStream output) Read a `Result` object from a stream in a vendor-specific format.
void	releaseFocus() Release the speech focus from this `Recognizer`.
void	removeResultListener(ResultListener listener) Remove a `ResultListener` from this `Recognizer`.
void	requestFocus() Request the speech focus for this `Recognizer` from the underlying speech recognition engine.
void	suspend() Temporarily suspend recognition while the application updates grammars prior to a `commitChanges` call.
void	writeVendorGrammar(OutputStream output, Grammar grammar) Store a grammar in a vendor-specific format.
void	writeVendorResult(OutputStream output, Result result) Store a finalized `Result` object in a vendor-specific format so that it can be re-loaded in a future session.

Field Detail

LISTENING

public static final long LISTENING

LISTENING is the bit of state that is set when an ALLOCATED Recognizer is listening to incoming audio for speech that may match an active grammar but has not yet detected speech.

A RECOGNIZER_PROCESSING event is issued to indicate a transition out of the LISTENING state and into the PROCESSING state.

A RECOGNIZER_SUSPENDED event is issued to indicate a transition out of the LISTENING state and into the SUSPENDED state.

A CHANGES_COMMITTED event is issued to indicate a transition into the LISTENING state from the SUSPENDED state.

See Also:: ALLOCATED, PROCESSING, SUSPENDED, getEngineState, RECOGNIZER_PROCESSING, RECOGNIZER_SUSPENDED, CHANGES_COMMITTED

PROCESSING

public static final long PROCESSING

PROCESSING is the bit of state that is set when an ALLOCATED Recognizer is producing a Result for incoming speech that may match an active grammar.

A RECOGNIZER_SUSPENDED event is issued to indicate a transition out of the PROCESSING state and into the SUSPENDED state when recgonition of a Result is completed.

A RECOGNIZER_PROCESSING event is issued to indicate a transition into the PROCESSING state from the LISTENING state when the start of a new result is detected.

See Also:: ALLOCATED, PROCESSING, SUSPENDED, getEngineState, RECOGNIZER_PROCESSING, RECOGNIZER_SUSPENDED

SUSPENDED

public static final long SUSPENDED

SUSPENDED is the bit of state that is set when an ALLOCATED Recognizer is temporarily suspended while grammar definition and grammar enabled settings are updated. The Recognizer enters this state whenever recognition of a Result is finalized, and in response to a call to suspend.

The primary difference between the SUSPENDED and PAUSED states of a Recognizer is that audio input is buffered in the SUSPENDED state. By contrast, the PAUSED state indicates that audio input to the Recognizer is being ignored. In addition, the SUSPENDED state is a temporary state, whereas a Recognizer can stay in the PAUSED state indefinately.

A CHANGES_COMMITTED event is issued to indicate a transition out of the SUSPENDED state and into the LISTENING state when all changes to grammars are committed to the recognition process.

A RECOGNIZER_SUSPENDED event is issued to indicate a transition into the SUSPENDED state from either the LISTENING state or PROCESSING state.

See Also:: ALLOCATED, PROCESSING, SUSPENDED, PAUSED, getEngineState, CHANGES_COMMITTED, RECOGNIZER_SUSPENDED

FOCUS_ON

public static final long FOCUS_ON

FOCUS_ON is the bit of state that is set when an ALLOCATED Recognizer has the speech focus of the underlying speech recognition engine.

As recognizer focus is gained and lost, a FOCUS_GAINED or FOCUS_LOST event is issued to indicate the state change. The requestFocus and releaseFocus methods allow management of speech focus.

See Also:: ALLOCATED, FOCUS_OFF, requestFocus, releaseFocus, FOCUS_GAINED, FOCUS_LOST, getEngineState

FOCUS_OFF

public static final long FOCUS_OFF

FOCUS_OFF is the bit of state that is set when an ALLOCATED Recognizer does not have the speech focus of the underlying speech recognition engine.

As recognizer focus is gained and lost, a FOCUS_GAINED or FOCUS_LOST event is issued to indicate the state change. The requestFocus and releaseFocus methods allow management of speech focus.

See Also:: ALLOCATED, FOCUS_ON, requestFocus, releaseFocus, FOCUS_GAINED, FOCUS_LOST, getEngineState

Method Detail

newRuleGrammar

public RuleGrammar newRuleGrammar(String name)
                                                   throws IllegalArgumentException,
                                                          EngineStateError

Create a new RuleGrammar for this recognizer with a specified grammar name. The new grammar is used for recognition only after changes are committed.

The newRuleGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:: name - name of the grammar to be created
Throws:: IllegalArgumentException - if grammar with name already exists; EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states

loadJSGF

public RuleGrammar loadJSGF(Reader JSGF)
                                             throws GrammarException,
                                                    IOException,
                                                    EngineStateError

Create a RuleGrammar from Java Speech Grammar Format text provided by the Reader. If the grammar contained in the Reader already exists, it is over-written. The new grammar is used for recognition only after changes are committed.

It is often useful to load JSGF from a String by creating a StringReader object with that string.

The caller is responsible for determining the character encoding of the JSGF document. The character encoding information contained in the JSGF header is ignored.

The loadJSGF methods operate as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:: JSGF - the Reader from which the grammar text is loaded
Throws:: GrammarException - if the JSGF text contains any errors; IOException - if an I/O error occurs; EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states
See Also:: loadJSGF(URL, String), loadJSGF(URL, String, boolean, boolean, Vector)

loadJSGF

public RuleGrammar loadJSGF(URL context,
                            String grammarName)
                                             throws GrammarException,
                                                    MalformedURLException,
                                                    IOException,
                                                    EngineStateError

Load a RuleGrammar and its imported grammars from Java Speech Grammar Format text from URLs or from system resources. The loaded grammars are used for recognition only after changes are committed.

The method returns a reference to the named RuleGrammar. The method never returns null since an exception is thrown if grammarName cannot be loaded successfully.

The method attempts to load all imports of grammarName, all imports of the imported grammars, and so on. This recursive load stops when grammars are reached that have already been loaded or when no more imports are found. The intent is to ensure that every grammar needed to use the named grammar is loaded.

For example, if we load grammar X, which imports grammar Y, which imports grammars A and B, then all four grammars are loaded. If any of the grammars are already loaded, then it and its imports are not reloaded.

JSGF allows fully-qualified rulename references without a corresponding import statement. This method also attempts to load all grammars referenced by a fully-qualified rulename not already referenced and loaded by a corresponding import statement.

The advanced loadJSGF method provides more control of the loading process. This method is equivalent to:

    loadJSGF(url, name, true, false, null);

(load imports, don't reload existing grammars, don't provide a list of loaded grammars.)

Locating Grammars

The context URL parameter is used as the first parameter of the URL(URL, String) constructor in the java.net package.

The grammarName is converted to a grammar filename. The conversion changes each each period character ('.') to a file separator ('/'). The ".gram" suffix is appended to identify the grammar file. The grammarName "com.sun.numbers" becomes the filename "com/sun/numbers.gram". This filename is used as the spec parameter in the URL constructor.

For example,

    loadJSGF(new URL("http://www.sun.com/"), "com.sun.numbers")

will look for the grammar in the URL "http://www.sun.com/com/sun/numbers.gram" and for its imports in a similar location.

If the derived URL does not exist, loadJSGF checks for a system resource with the grammar file using the ClassLoader.getSystemResource method. This allows grammars to be included in the CLASSPATH.

If the context is null, the grammars are searched for only as a system resource.

Reading Grammars

For each grammar it loads, the recognizer determines the file's character encoding by reading the JSGF header.

An exception is thrown if (1) any JSGF syntax problems are found, (2) if a grammar found in a URL does not match the expected name, or (3) if a grammar cannot be located as either a URL or system resource.

If an exception is thrown part way through loading a set of grammars the list of loaded grammars not explicitly available. The recognizer does not attempt to remove any partially loaded grammars.

Parameters:: base - the URL context from which grammar locations are derived or null to load exclusively from system resources; grammarName - the name of the grammar to be loaded
Returns:: a reference to grammarName
Throws:: GrammarException - if any loaded JSGF text contains an error; MalformedURLException - if problem encountered creating a URL; IOException - if an I/O error occurs; EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states
See Also:: loadJSGF(java.io.Reader), loadJSGF(URL, String, boolean, boolean, Vector), URL(java.net.URL, java.net.String)

loadJSGF

public RuleGrammar loadJSGF(URL context,
                            String grammarName,
                            boolean loadImports,
                            boolean reloadGrammars,
                            Vector loadedGrammars)
                                             throws GrammarException,
                                                    MalformedURLException,
                                                    IOException,
                                                    EngineStateError

Load a RuleGrammar in Java Speech Grammar Format text from a URL or from system resources and optionally load its imports. This method provide an additional control over whether grammars are reloaded even if they have already been loaded, and allows caller to receive a list of all grammars loaded by the Recognizer. The loaded grammars are used for recognition only after changes are committed.

The three additional parameters of this method provide the following extensions over the loadJSGF(URL, String) method:

loadImports: if false, the method only loads the RuleGrammar specified by the name parameter.
If true, the method behaves like the loadJSGF(URL, String) method and recursively loads imported grammars.
reloadGrammars: if true, the method always loads a RuleGrammar, even if it is already loaded into the Recognizer. The previous version of the grammar is overwritten.
If false, the method behaves like the loadJSGF(URL, String) method and does not load grammars that are already loaded, or their imports.
loadedGrammars: if non-null, then as the Recognizer loads any grammar it appends a reference to that RuleGrammar to the Vector.

Parameters:: base - the URL context from which grammar locations are derived or null to load exclusively from system resources; grammarName - the name of the grammar to be loaded; loadImports - if true, grammars imported by grammarName are loaded plus their imports; reloadGrammars - if true reload all grammars and imports, if false do not load grammars already loaded into the Recognizer; loadedGrammars - if non-null a reference to each loaded RuleGrammar is appended as it is loaded
Returns:: a reference to grammarName
Throws:: GrammarException - if any loaded JSGF text contains an error; MalformedURLException - if problem encountered creating a URL; IOException - if an I/O error occurs; EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states
See Also:: loadJSGF(java.io.Reader), loadJSGF(URL, String)

getRuleGrammar

public RuleGrammar getRuleGrammar(String name)
                                                   throws EngineStateError

Get the RuleGrammar with the specified name. Returns null if the grammar is not known to the Recognizer.

The getRuleGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:: name - the name of the grammar to be returned
Returns:: a RuleGrammar reference or null
Throws:: EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states

listRuleGrammars

public RuleGrammar[] listRuleGrammars()
                                                       throws EngineStateError

List the RuleGrammars known to the Recognizer. Returns null if there are no grammars.

The listRuleGrammars method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Throws:: EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states

deleteRuleGrammar

public void deleteRuleGrammar(RuleGrammar grammar)
                      throws IllegalArgumentException,
                             EngineStateError

Delete a RuleGrammar from the Recognizer. The grammar deletion only takes effect when all grammar changes are committed.

Recognizers may chose to ignore the deletion of built-in grammars.

The deleteRuleGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Throws:: IllegalArgumentException - if the Grammar is not known to the Recognizer; EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states
See Also:: commitChanges, CHANGES_COMMITTED

getDictationGrammar

public DictationGrammar getDictationGrammar(String name)
                                                             throws EngineStateError

Return the DictationGrammar for a Recognizer. Typically, the name parameter is null to get access to the default DictationGrammar for the Recognizer.

If the Recognizer does not support dictation, or if it does have a DictationGrammar with the specified name, then the method returns null.

An application can determine whether the Recognizer supports dictation by calling the isDictationGrammarSupported method of the RecognizerModeDesc.

Note: the name parameter is provided for future extenion of the API to allow more than one DictationGrammar to be defined.

The getDictationGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Throws:: EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states
See Also:: isDictationGrammarSupported

commitChanges

public void commitChanges()
                  throws GrammarException,
                         EngineStateError

Commit changes to all loaded grammars and all changes of grammar enabling since the last commitChanges. Because all changes are applied atomically (all at once) the application does not need to be concerned with intermediate states as it changes grammar definitions and enabling.

The commitChanges call first checks that all the loaded grammars are legal. If there are any problems with the current definition of any RuleGrammar an exception is thrown. Problems might include undefined rule name, illegal recursion and so on (see the Java Speech Grammar Format Specification and the GrammarSyntaxDetail class documentation for details).

The commitChanges call is asynchronous (the changes have not necessarily been committed when the call returns). When the changes have been committed, a CHANGES_COMMITTED event is issued to all RecognizerListeners and to the GrammarListeners of all changed Grammars.

Immediately following the CHANGES_COMMITTED event, a GRAMMAR_CHANGES_COMMITTED GrammarEvent is issued to the GrammarListeners of all changed grammars.

The roll of commitChanges in applying grammar changes in described in the documentation for the Grammar interface. The effect of the commitChanges method upon Recognizer states is described above. The use of suspend with commitChanges and their use for processing asynchronous non-speech events are also described above.

It is not an error to commitChanges when no grammars have been changed. However, the Recognizer performs state transitions in the same way as when grammars are changed.

The commitChanges method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Throws:: GrammarException - if the loaded grammars contain any logical errors; EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states
See Also:: LISTENING, PROCESSING, SUSPENDED, suspend, CHANGES_COMMITTED

suspend

public void suspend()
            throws EngineStateError

Temporarily suspend recognition while the application updates grammars prior to a commitChanges call. The suspend call places the Recognizer in the SUSPENDED state. While in that state the incoming audio is buffered. The buffered audio is processed after the recognizer has committed grammar changes and returned to the LISTENING state.

The primary difference between the suspend and pause methods is that audio is buffered while a Recognizer is suspended whereas incoming audio is ignored while in the PAUSED state. Also, the SUSPENDED state should only be visited temporarily, whereas a Recognizer can be PAUSED indefinately.

The suspend method is asynchronous. When the call returns, the recognizer is not necessarily suspended. The getEngineState method, or the RECOGNIZER_SUSPENDED events can be used to determine when the recognizer is actually suspended.

The use of suspend with commitChanges for handling atomic grammar changes and for handling asynchronous events are described above.

Calls to suspend and commitChanges do not nest. A single call to commitChanges can release the Recognizer after multiple calls to suspend.

The suspend method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Throws:: EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states
See Also:: commitChanges, SUSPENDED, RECOGNIZER_SUSPENDED

forceFinalize

public void forceFinalize(boolean flush)
                  throws EngineStateError

If the Recognizer is in the PROCESSING state (producing a Result), force the Recognizer to immediately complete processing of that result by finalizing it. It is acceptable behavior for a Recognizer to automatically reject the current result.

The flush flag indicates whether the recognizer's internally buffered audio should be processed before forcing the finalize. Applications needing immediate cessation of recognition should request a flush. If the force finalize is a response to a user event (e.g. keyboard or mouse press) then the buffer is typically not flushed because incoming speech from a user could be lost.

The state behavior of the Recognizer is the same as if the Result had been finalized because of end-of-utterance. The Recognizer will transition to the SUSPENDED state.

The forceFinalize method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Throws:: EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states

requestFocus

public void requestFocus()
                 throws EngineStateError

Request the speech focus for this Recognizer from the underlying speech recognition engine. When the focus is received, a FOCUS_GAINED event is issued to RecognizerListeners and the Recognizer changes state from FOCUS_ON to FOCUS_OFF.

Since one one application may have recognition focus at any time, applications should only request focus when confident that the user is speaking to that application. Speech focus and other focus issues are discussed above in more detail.

It is not an error for an application to request focus for a Recognizer that already has speech focus.

The requestFocus method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Throws:: EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states
See Also:: releaseFocus, FOCUS_ON, FOCUS_GAINED, getEngineState

releaseFocus

public void releaseFocus()
                 throws EngineStateError

Release the speech focus from this Recognizer. A FOCUS_LOST event is issued to RecognizerListeners once the focus is released and the Recognizer state changes from FOCUS_OFF to FOCUS_ON.

Since one one application may have recognition focus at any time, applications should release focus whenever it is not required. Speech focus and other focus issues are discussed above in more detail.

It is not an error for an application to release focus for a Recognizer that does not have speech focus.

Focus is implicitly released when a Recognizer is deallocated.

The releaseFocus method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Throws:: EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states
See Also:: requestFocus, FOCUS_OFF, FOCUS_LOST, getEngineState

addResultListener

public void addResultListener(ResultListener listener)

Request notifications of all events for all Result produced by this Recognizer. An application can attach multiple ResultListeners to a Recognizer. A listener is removed with the removeResultListener method.

ResultListeners attached to a Recognizer are the only ResultListeners to receive the RESULT_CREATED event and all subsequent events.

ResultListener objects can also be attached to any Grammar or to any Result. A listener attached to the Grammar receives all events that match that Grammar following a GRAMMAR_FINALIZED event. A listener attached to a Result receives all events for that result from the time at which the listener is attached.

A ResultListener can be attached or removed in any Engine state.

See Also:: removeResultListener, addResultListener, addResultListener, RESULT_CREATED, GRAMMAR_FINALIZED

removeResultListener

public void removeResultListener(ResultListener listener)

Remove a ResultListener from this Recognizer.

A ResultListener can be attached or removed in any Engine state.

See Also:: addResultListener, removeResultListener, removeResultListener

getRecognizerProperties

public RecognizerProperties getRecognizerProperties()

Return the RecognizerProperties object (a JavaBean). The method returns exactly the same object as the getEngineProperties method in the Engine interface. However, with the getRecognizerProperties method, an application does not need to cast the return value.

The RecognizerProperties are available in any state of an Engine. However, changes only take effect once an engine reaches the ALLOCATED state.

Returns:: the RecognizerProperties object for this engine
See Also:: getEngineProperties

getSpeakerManager

public SpeakerManager getSpeakerManager()
                                                         throws SecurityException

Return an object which provides management of the speakers of a Recognizer. Returns null if the Recognizer does not store speaker data - that is, if it is a speaker-independent recognizer in which all speakers are handled the same.

A getSpeakerManager returns successfully in any state of a Recognizer. The SpeakerManager methods that list speakers and set the current speaker operate in any Recognizer state but only take effect in the ALLOCATED state. This allows an application can set the initial speaker prior to allocating the engine. Other methods of the SpeakerManager only operate in the ALLOCATED state.

Returns:: the SpeakerManager for this Recognizer
Throws:: SecurityException - if the application does not have accessSpeakerProfiles permission

readVendorGrammar

public Grammar readVendorGrammar(InputStream input)
                                                  throws VendorDataException,
                                                         IOException,
                                                         EngineStateError

Create a new grammar by reading in a grammar stored in a vendor-specific format. The data could have been stored using the writeVendorGrammar method. The documentation for the writeVendorGrammar method describes the use of vendor grammar formats.

If a grammar of the same name already exists, it is over-written.

The readVendorGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:: input - InputStream from which grammar is loaded
Returns:: reference to the loaded grammar
Throws:: VendorDataException - if the input data format is not known to the Recognizer; IOException - if an I/O error occurs.; EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states

writeVendorGrammar

public void writeVendorGrammar(OutputStream output,
                               Grammar grammar)
                       throws IOException,
                              EngineStateError

Store a grammar in a vendor-specific format. The data can be re-loaded at a future time by the readVendorGrammar method.

The output format will be specific to the type of recognizer that writes it. For example, data written by an Acme Command and Control Recognizer will be readable only by another Acme Command and Control Recognizer or by other recognizers that understand it's format. When portability is required, use the Java Speech Grammar Format.

Why is a Vendor grammar format useful? The recognizer can store information that makes reloading of the grammar faster than when JSGF is used. The recognizer may also store additional information (e.g. pronunciation, statistical and acoustic data) that improve recognition using this grammar. The writeVendorGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:: output - OutputStream where grammar is written; grammar - Grammar to be written
Throws:: IOException - if an I/O error occurs.; EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states

readVendorResult

public Result readVendorResult(InputStream output)
                                                throws VendorDataException,
                                                       IOException,
                                                       EngineStateError

Read a Result object from a stream in a vendor-specific format. The return value will include the best-guess tokens, and may include N-best results, audio data, timing data, training information and other data the is optionally provided with a finalized Result.

The call returns null upon failure. Because result objects are stored in a vendor-specific format they cannot normally be loaded by incompatible recognizers.

The readVendorResult method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:: input - InputStream from which Result is loaded
Returns:: reference to the loaded result
Throws:: VendorDataException - if the input data format is not known to the Recognizer; IOException - if an I/O error occurs.; EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states

writeVendorResult

public void writeVendorResult(OutputStream output,
                              Result result)
                      throws IOException,
                             ResultStateError,
                             EngineStateError

Store a finalized Result object in a vendor-specific format so that it can be re-loaded in a future session. All the current information associated with the result is stored. If the application will not need audio data or training information in a future session, they should release that information (through the FinalResult interface) before writing the result to reduce storage requirements.

The writeVendorGrammar method operates as defined when the Recognizer is in the ALLOCATED state. The call blocks if the Recognizer in the ALLOCATING_RESOURCES state and completes when the engine reaches the ALLOCATED state. An error is thrown if the Recognizer is in the DEALLOCATED or DEALLOCATING_RESOURCES state.

Parameters:: output - OutputStream where the result is written; result - Result to be written
Throws:: ResultStateError - if the Result is not in a finalized state; IOException - if an I/O error occurs.; EngineStateError - if called for a Recognizer in the DEALLOCATED or DEALLOCATING_RESOURCES states


Overview \| Package \| Class \| Tree \| Index \| Help
PREV CLASS \| NEXT CLASS	FRAMES \| NO FRAMES
SUMMARY: INNER \| FIELD \| CONSTR \| METHOD	DETAIL: FIELD \| CONSTR \| METHOD


Overview \| Package \| Class \| Tree \| Index \| Help
PREV CLASS \| NEXT CLASS	FRAMES \| NO FRAMES
SUMMARY: INNER \| FIELD \| CONSTR \| METHOD	DETAIL: FIELD \| CONSTR \| METHOD


Overview \| Package \| Class \| Tree \| Index \| Help
PREV CLASS \| NEXT CLASS	FRAMES \| NO FRAMES
SUMMARY: INNER \| FIELD \| CONSTR \| METHOD	DETAIL: FIELD \| CONSTR \| METHOD