Interface javax.speech.recognition.Grammar


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.Grammar

Subinterfaces:: DictationGrammar, RuleGrammar

public abstract interface Grammar

Parent interface supported by all recognition grammars including DictationGrammar and RuleGrammar. A Grammar defines a set of tokens (words) that may be spoken and the patterns in which those tokens may be spoken. Different grammar types (dictation vs. rule) define the words and the patterns in different ways.

The core functionality provided through the Grammar interface includes:

Naming: each grammar of a Recognizer has a unique name.
Enabling: grammars may be enabled or disabled for activation of recognition.
Activation: the activation mode can be set and the activation state tested.
Adding and removing GrammarListeners for grammar-related events.
Adding and removing ResultListeners to receive result events for results matching the Grammar.
Access the Recognizer that owns the grammar

Each Grammar is associated with a specific Recognizer. All grammars are located, created and managed through the Recognizer interface. The basic steps in using any Grammar are:

Create a new Grammar or get a reference to an existing grammar through the Recognizer interface.
Attach a ResultListener to get results.
As necessary, setup or modify the grammar for the application's context.
Enabled and disable recognition of the Grammar as required by the application's context.
Commit grammar changes and enabled state into the recognition process.
Repeat the update, enable and commit steps as required.
For application-created grammars, delete the Grammar when it is no longer needed.

Grammar Types

There are two types of Grammar: DictationGrammar and RuleGrammar Both are defined by interfaces that extend the Grammar interface. All recognizers support RuleGrammars. A recognizer may optionally support a DictationGrammar.

The RuleGrammar and DictationGrammar interfaces define specialized mechanisms for controlling and modifying those types of grammar.

Grammar Activation

When a Grammar is active, the Recognizer listens to incoming audio for speech that matches that Grammar. To be activated, an application must first set the enabled property to true (enable activation) and set the activationMode property to indicate the activation conditions.

There are three activation modes: RECOGNIZER_FOCUS, RECOGNIZER_MODAL and GLOBAL. For each mode a certain set of activation conditions must be met for the grammar to be activated for recognition. The activation conditions are determined by Recognizer focus and possibly by the activation of other grammars. Recognizer focus is managed with the requestFocus and releaseFocus methods of a Recognizer.

The modes are listed here by priority. Always use the lowest priority mode possible.

GLOBAL activation mode: if enabled, the Grammar is always active irrespective of whether the Recognizer of this application has focus.
RECOGNIZER_MODAL activation mode: if enabled, the Grammar is always active when the Recognizer of this application has focus. Furthermore, enabling a modal grammar deactivates any grammars in the same Recognizer with the RECOGNIZER_FOCUS activation mode.
RECOGNIZER_FOCUS activation mode (default): if enabled, the Grammar is active when the Recognizer of this application has focus. The exception is that if any other grammar of this application is enabled with RECOGNIZER_MODAL activation mode, then this grammar is not activated.

The current activation state of a grammar can be tested with the isActive method. Whenever a grammar's activation changes either a GRAMMAR_ACTIVATED or GRAMMAR_DEACTIVATED event is issued to each attached GrammarListener.

An application may have zero, one or many grammar enabled at any time. As the conventions below indicate, well-behaved applications always minimize the number of active grammars.

The activation and deactivation of grammars is independent of PAUSED and RESUMED states of the Recognizer. However, when a Recognizer is PAUSED, audio input to the Recognizer is turned off, so speech can't be detected. Note that just after pausing a recognizer there may be some remaining audio in the input buffer that could contain recognizable speech and thus an active grammar may continue to receive result events.

Well-behaved applications adhere to the following conventions to minimize impact on other applications and other components of the same application:

Never apply the GLOBAL activation mode to a DictationGrammar.
Always use the default activation mode RECOGNIZER_FOCUS unless there is a good reason to use another mode.
Only use the RECOGNIZER_MODAL when certain that deactivating RECOGNIZER_FOCUS grammars will not adversely affect the user interface.
Minimize the complexity and the number of RuleGrammars with GLOBAL activation mode.
Only enable a grammar when it is appropriate for a user to say something matching that grammar. Otherwise disable the grammar to improve recognition response time and recognition accuracy for other grammars.
Only request focus when confident that the user's speech focus (attention) is directed to grammars of your application. Release focus when it is not required.

The general principal underlying these conventions is that increasing the number of active grammars and/or increasing the complexity of those grammars can lead to slower response time, greater CPU load and reduced recognition accuracy (more mistakes).

Committing Changes

Grammars can be dynamically changed and enabled and disabled. Changes may be necessary as the application changes context, as new information becomes available and so on. As with graphical interface programming most grammar updates occur during processing of events. Very often grammars are updated in response to speech input from a user (a ResultEvent). Other asynchronous events (e.g., AWTEvents) are another common trigger of grammar changes. Changing grammars during normal operation of a recognizer is usually necessary to ensure natural and usable speech-enabled applications.

Different grammar types allow different types of run-time change. RuleGrammars can be created and deleted during normal recognizer operation. Also, any aspect of a created RuleGrammar can be redefined: rules can be modified, deleted or added, imports can be changed an so on. Certain properties of a DictationGrammar can be changed: the context can be updated and the vocabulary modified.

For any grammar changes to take effect they must be committed. Committing changes builds the grammars into a format that can be used by the internal processes of the recognizer and applies those changes to the processing of incoming audio.

There are two ways in which a commit takes place:

An explicit call by an application to the commitChanges method of the Recognizer. The documentation for the method describes when and how changes are committed when called. (The commitChanges method is typically used in conjunction with the suspend method of Recognizer.)
Changes to all grammars are implicitly committed at the completion of processing of a result finalization event (either a RESULT_ACCEPTED or RESULT_REJECTED event). This simplifies the common scenario in which grammars are changed during result finalization process because the user's input has changed the application's state. (This implicit commit is deferred following a call to suspend and until a call to commitChanges.)

The Recognizer issues a CHANGES_COMMITTED event to signal that changes have been committed. This event signals a transition from the SUSPENDED state to the LISTENING state. Once in the LISTENING state the Recognizer resumes the processing of incoming audio with the newly committed grammars.

Also each changed Grammar receives a GRAMMAR_CHANGES_COMMITTED through attached GrammarListeners whenever changes to it are committed.

The commit changes mechanism has two important properties:

Updates to grammar definations and the enabled property take effect atomically (all changes take effect at once). There are no intermediate states in which some, but not all, changes have been applied.
It is a method of Recognizer so all changes to all Grammars are committed at once. Again, there are no intermediate states in which some, but not all, changes have been applied.

Grammar and Result Listeners

An application can attach one or more GrammarListeners to any Grammar. The listener is notified of status changes for the Grammar: when changes are committed and when activation changes.

An application can attach one or more ResultListener objects to each Grammar. The listener is notified of all events for all results that match this grammar. The listeners receive ResultEvents starting with the GRAMMAR_FINALIZED event (not the preceding RESULT_CREATED or RESULT_UPDATED events).

See Also:: RuleGrammar, DictationGrammar, GrammarListener, ResultListener, Result, Recognizer, commitChanges

Field Summary
static int	GLOBAL Value of activation mode in which the `Grammar` is active for recognition irrespective of the focus state of the `Recognizer`.
static int	RECOGNIZER_FOCUS Default value of activation mode that requires the `Recognizer` have focus and that there be no enabled grammars with `RECOGNIZER_MODAL` mode for the grammar to be activated.
static int	RECOGNIZER_MODAL Value of activation mode that requires the `Recognizer` have focus for the grammar to be activated.

Method Summary
void	addGrammarListener(GrammarListener listener) Request notifications of events of related to this `Grammar`.
void	addResultListener(ResultListener listener) Request notifications of events from any `Result` that matches this `Grammar`.
int	getActivationMode() Return the current activation mode for a `Grammar`.
String	getName() Get the name of a grammar.
Recognizer	getRecognizer() Returns a reference to the `Recognizer` that owns this grammar.
boolean	isActive() Test whether a `Grammar` is currently active for recognition.
boolean	isEnabled() Return the `enabled` property of a `Grammar`.
void	removeGrammarListener(GrammarListener listener) Remove a listener from this `Grammar`.
void	removeResultListener(ResultListener listener) Remove a `ResultListener` from this `Grammar`.
void	setActivationMode(int mode) Set the activation mode of a `Grammar` as `RECOGNIZER_FOCUS`, `RECOGNIZER_MODAL`, or `GLOBAL`.
void	setEnabled(boolean enabled) Set the enabled property of a `Grammar`.

Field Detail

RECOGNIZER_FOCUS

public static final int RECOGNIZER_FOCUS

Default value of activation mode that requires the Recognizer have focus and that there be no enabled grammars with RECOGNIZER_MODAL mode for the grammar to be activated. This is the lowest priority activation mode and should be used unless there is a user interface design reason to use another mode.

The activation conditions for the RECOGNIZER_FOCUS mode are describe above.

See Also:: setActivationMode, RECOGNIZER_MODAL, GLOBAL

RECOGNIZER_MODAL

public static final int RECOGNIZER_MODAL

Value of activation mode that requires the Recognizer have focus for the grammar to be activated.

The activation conditions for the RECOGNIZER_MODAL mode are describe above.

See Also:: setActivationMode, RECOGNIZER_FOCUS, GLOBAL

GLOBAL

public static final int GLOBAL

Value of activation mode in which the Grammar is active for recognition irrespective of the focus state of the Recognizer.

The activation conditions for the GLOBAL mode are describe above.

See Also:: setActivationMode, RECOGNIZER_FOCUS, RECOGNIZER_MODAL

Method Detail

getRecognizer

public Recognizer getRecognizer()

Returns a reference to the Recognizer that owns this grammar.

getName

public String getName()

Get the name of a grammar. A grammar's name must be unique for a recognizer. Grammar names use a similar naming convention to Java classes. The naming convention are defined in the Java Speech Grammar Format Specification.

Grammar names are used with a RuleGrammar for resolving imports and references between grammars. The name of a RuleGrammar is set when the grammar is created (either by loading a JSGF document or creating a new RuleGrammar).

The name of a DictationGrammar should reflect the language domain it supports. For example: com.acme.dictation.us.general for general US Dictation from Acme corporation. Since a DictationGrammar is built into a Recognizer, its name is determined by the Recognizer.

See Also:: DictationGrammar, RuleGrammar

setEnabled

public void setEnabled(boolean enabled)

Set the enabled property of a Grammar. A change in the enabled property takes effect only after grammar changes are committed. Once a grammar is enabled and when the activation conditions are met, it is activated for recognition. When a grammar is activated, the Recognizer listens to incoming audio for speech that matches the grammar and produces a Result when matching speech is detected.

The enabled property of a grammar is tested with the isEnabled method. The activation state of a grammar is tested with the isActive method.

The RuleGrammar interface extends the enabling property to allow individual rules to be enabled and disabled.

See Also:: commitChanges, setEnabled(boolean), setEnabled(java.lang.String, boolean), setEnabled(java.lang.String[], boolean), isEnabled

isEnabled

public boolean isEnabled()

Return the enabled property of a Grammar. More specialized behaviour is specified by the RuleGrammar interface.

See Also:: setEnabled, isEnabled(), isEnabled(java.lang.String)

setActivationMode

public void setActivationMode(int mode)
                      throws IllegalArgumentException

Set the activation mode of a Grammar as RECOGNIZER_FOCUS, RECOGNIZER_MODAL, or GLOBAL. The role of the activation mode in the activation conditions for a Grammar are described above. The default activation mode - RECOGNIZER_FOCUS - should be used unless there is a user interface design reason to use another mode.

The individual rules of a RuleGrammar can be separately enabled and disabled. However, all rules share the same ActivationMode since the mode is a property of the complete Grammar. A consequence is that all enabled rules of a RuleGrammar are activated and deactivated together.

A change in activation mode only takes effect once changes are committed. For some recognizers changing the activation mode is computationally expensive.

The activation mode of a grammar can be tested by the getActivationMode method.

[Note: future releases may modify the set of activation modes.]

Throws:: IllegalArgumentException - if an attempt is made to set GLOBAL mode for a DictationGrammar
See Also:: getActivationMode, RECOGNIZER_FOCUS, RECOGNIZER_MODAL, GLOBAL, setEnabled, isActive, commitChanges

getActivationMode

public int getActivationMode()

Return the current activation mode for a Grammar. The default value for a grammar is RECOGNIZER_FOCUS.

See Also:: setActivationMode, setEnabled, isActive

isActive

public boolean isActive()

Test whether a Grammar is currently active for recognition. When a grammar is active, the recognizer is matching incoming audio against the grammar (and other active grammars) to detect speech that matches the grammar.

A Grammar is activated for recognition if the enabled property is set to true and the activation conditions are met. Activation is not directly controlled by applications and so can only be tested (there is no setActive method).

Rules of a RuleGrammar can be individuallly enabled and disabled. However all rules share the same ActivationMode and the same activation state. Thus, when a RuleGrammar is active, all the enabled rules of the grammar are active for recognition.

Changes in the activation state are indicated by GRAMMAR_ACTIVATED and GRAMMAR_DEACTIVATED events issued to the GrammarListener. A change in activation state can follow these RecognizerEvents:

A CHANGES_COMMITTED event that applies a change in the enabled state or ActivationMode of this or another Grammar.
A FOCUS_GAINED or FOCUS_LOST event.

See Also:: setEnabled, setActivationMode, GRAMMAR_ACTIVATED, GRAMMAR_DEACTIVATED, CHANGES_COMMITTED, FOCUS_GAINED, FOCUS_LOST

addGrammarListener

public void addGrammarListener(GrammarListener listener)

Request notifications of events of related to this Grammar. An application can attach multiple listeners to a Grammar.

See Also:: removeGrammarListener

removeGrammarListener

public void removeGrammarListener(GrammarListener listener)

Remove a listener from this Grammar.

See Also:: addGrammarListener

addResultListener

public void addResultListener(ResultListener listener)

Request notifications of events from any Result that matches this Grammar. An application can attach multiple ResultListeners to a Grammar. A listener is removed with the removeResultListener method.

A ResultListener attached to a Grammar receives result events starting from the GRAMMAR_FINALIZED event - the event which indicates that the matched grammar is known. A ResultListener attached to a Grammar will never receive a RESULT_CREATED event and does not receive any RESULT_UPDATED events that occurred before the GRAMMAR_FINALIZED event. A ResultListener attached to a Grammar is guaranteed to receive a result finalization event - RESULT_ACCEPTED or RESULT_REJECTED - some time after the GRAMMAR_FINALIZED event.

ResultListener objects can also be attached to a Recognizer and to any Result. A listener attached to the Recognizer receives all events for all results produced by that Recognizer. A listener attached to a Result receives all events for that result from the time at which the listener is attached.

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

removeResultListener

public void removeResultListener(ResultListener listener)

Remove a ResultListener from this Grammar.

See Also:: addResultListener, removeResultListener, removeResultListener


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