javax.speech.recognition
Interface Grammar

All Known Subinterfaces:

RuleGrammar

public interface Grammar

Parent interface supported by all types of recognition grammars. A recognition grammar defines a set of tokens (such as words) that may be spoken and the pattern in which those tokens may be spoken. Different Grammar types define the words and the patterns in different ways.

All Grammars are located, created and managed through the GrammarManager interface. The basic steps in using any Grammar are:

• Create a new Grammar or get an existing Grammar through the GrammarManager interface.
• Attach a ResultListener to get Results.
• As necessary, update the Grammar for the application's context.
• Change the Grammars activatable property as required by the application's context for recognition.
• Commit changes into the recognition process.
• Repeat the update, activatable change, and commit steps as required.
• For application-created Grammars, delete the Grammar when it is no longer needed.

Grammar Activation

When a Grammar is active at the top level, the associated Recognizer listens to incoming audio for speech that directly matches that Grammar. To be activated, an application must ensure that the activatable property is true (see isActivatable) and specify the desired activation mode with setActivationMode.

There are four activation modes (listed in priority order, from lowest to highest): ACTIVATION_INDIRECT, ACTIVATION_FOCUS, ACTIVATION_MODAL and ACTIVATION_GLOBAL. An ACTIVATION_INDIRECT Grammar is used indirectly through other Grammars. For the other modes, a certain set of activation conditions must be met for the Grammar to be activated for recognition. The activation conditions are determined by the activation mode, recognition focus and possibly by the activation of other Grammars. Recognition focus is managed with the requestFocus and releaseFocus methods.

The specific activation conditions for each activation mode are described with each mode. The default activation mode is ACTIVATION_FOCUS.

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

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 not processed, so speech cannot 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 ResultEvents.

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

• For Grammars loaded directly by the Recognizer, always use the default activation mode ACTIVATION_FOCUS unless there is a good reason to use another mode.
• Only use ACTIVATION_MODAL when certain that deactivating Grammars that have ACTIVATION_FOCUS will not adversely affect the user interface.
• Minimize the complexity and the number of Grammars that have ACTIVATION_GLOBAL activation mode.
• Keep the activatable property true only when it is appropriate for a user to say something matching that Grammar. This can also improve the Recognizers response time and accuracy.
• Only requestFocus when confident that the user's recognition focus (attention) is directed to Grammars of your application. ReleaseFocus 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 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., GUI events) 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.

For any Grammar changes to affect recognition they must be committed. Committing changes converts 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 committing Grammar changes occurs:

1. An explicit call by an application to the resume method of the Recognizer. The documentation for that method describes when and how changes are committed when called. This method is used in conjunction with the pause method of Recognizer.
2. 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. In this case, an internal pause(BUFFER_MODE) is called before ResultListeners are called followed by an internal call to resume.

The Recognizer issues a CHANGES_COMMITTED event to signal that changes have been committed. This event signals a transition from the PAUSED state to the RESUMED state.

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

If there is an unrecoverable problem during the resume operation, then a CHANGES_REJECTED event signals that changes have been rejected and are lost. Additionally, any Grammars that would have changed receive a GRAMMAR_CHANGES_REJECTED event. In this case, the last committed Grammar changes remain in effect when the Recognizer enters the RESUMED state.

The resume method has the following important property:

Changes to Grammars take effect atomically (all changes take effect at once). There are no intermediate states in which some, but not all, changes have been applied within a Recognizer.

In some applications, Grammar changes may be ready to process before the application is ready to resume. In this case, the application may call processGrammars. If no further changes are made before resume, an implementation may process changes to save time once resume is called.

See Also:

GrammarListener, GrammarEvent, GRAMMAR_ACTIVATED, GRAMMAR_DEACTIVATED, GRAMMAR_CHANGES_COMMITTED, GRAMMAR_CHANGES_REJECTED, Recognizer, requestFocus, releaseFocus, pause, resume, PAUSED, RESUMED, processGrammars, RecognizerEvent, CHANGES_COMMITTED, CHANGES_REJECTED, Result, ResultListener, ResultEvent, RESULT_ACCEPTED, RESULT_REJECTED, GRAMMAR_FINALIZED

Field Summary

static int	ACTIVATION_FOCUS Constant representing the default activation mode for a Grammar loaded directly by the GrammarManager.
static int	ACTIVATION_GLOBAL Constant value representing the activation mode in which this Grammar is active for recognition irrespective of the recognition focus state.
static int	ACTIVATION_INDIRECT Constant representing the activation mode for a Grammar used indirectly by other Grammars.
static int	ACTIVATION_MODAL Constant representing an activation mode for a Grammar that can also deactivate other active Grammars.

Method Summary

void	addGrammarListener(GrammarListener listener) Requests notifications of GrammarEvents related to this Grammar.
void	addResultListener(ResultListener listener) Requests notifications of ResultEvents from any Result that matches this Grammar.
int	getActivationMode() Returns the current activation mode for a Grammar.
GrammarManager	getGrammarManager() Returns the GrammarManager that manages this Grammar.
String	getReference() Gets the reference of this Grammar.
boolean	isActivatable() Returns the activatable property of this Grammar.
boolean	isActive() Tests whether this Grammar is currently active for top-level recognition.
void	removeGrammarListener(GrammarListener listener) Removes a GrammarListener from this Grammar.
void	removeResultListener(ResultListener listener) Removes a ResultListener from this Grammar.
void	setActivatable(boolean activatable) Sets the activatable property of this Grammar.
void	setActivationMode(int mode) Sets the activation mode of this Grammar.

Field Detail

ACTIVATION_INDIRECT

static final int ACTIVATION_INDIRECT

Constant representing the activation mode for a Grammar used indirectly by other Grammars. This is the default activation mode for Grammars loaded indirectly by reference. This activation mode is also useful for shared Grammars.

A Grammar with this activation mode is not activated at the top level for recognition. To be used for recognition, an active top-level Grammar must refer to this Grammar (directly or indirectly).

This Grammar must be activatable as indicated by isActivatable.

For Grammars intended for top-level activation, use one of the other activation modes.

See Also:

setActivationMode, isActivatable, ACTIVATION_FOCUS, ACTIVATION_MODAL, ACTIVATION_GLOBAL, Constant Field Values

ACTIVATION_FOCUS

static final int ACTIVATION_FOCUS

Constant representing the default activation mode for a Grammar loaded directly by the GrammarManager. Activation requires recognition focus and that there be no activatable Grammars with ACTIVATION_MODAL activation mode.

This Grammar must be activatable as indicated by isActivatable.

This is the lowest priority top-level activation mode and should be used unless there is a user interface design reason to use another mode.

See Also:

setActivationMode, isActivatable, ACTIVATION_INDIRECT, ACTIVATION_MODAL, ACTIVATION_GLOBAL, GrammarManager, Constant Field Values

ACTIVATION_MODAL

static final int ACTIVATION_MODAL

Constant representing an activation mode for a Grammar that can also deactivate other active Grammars. Activation requires recognition focus for this Grammar to be activated. Furthermore, Grammars in the same GrammarManager with ACTIVATION_FOCUS activation mode are deactivated at the top level.

This Grammar must be activatable as indicated by isActivatable.

The ACTIVATION_FOCUS mode is preferred unless the user interface design warrants this activation mode.

See Also:

setActivationMode, isActivatable, ACTIVATION_INDIRECT, ACTIVATION_FOCUS, ACTIVATION_GLOBAL, GrammarManager, Constant Field Values

ACTIVATION_GLOBAL

static final int ACTIVATION_GLOBAL

Constant value representing the activation mode in which this Grammar is active for recognition irrespective of the recognition focus state.

This Grammar must be activatable as indicated by isActivatable.

This is the highest priority activation mode and should be used with care. The ACTIVATION_FOCUS mode is preferred unless the user interface design warrants this activation mode.

See Also:

setActivationMode, isActivatable, ACTIVATION_INDIRECT, ACTIVATION_FOCUS, ACTIVATION_MODAL, Constant Field Values

Method Detail

addGrammarListener

void addGrammarListener(GrammarListener listener)

Requests notifications of GrammarEvents related to this Grammar. An application can attach multiple listeners to a Grammar.

The setGrammarMask method controls masking of GrammarEvents.

Parameters:

listener - a listener for GrammarEvents

See Also:

removeGrammarListener, GrammarEvent, setGrammarMask

addResultListener

void addResultListener(ResultListener listener)

Requests notifications of ResultEvents from any Result that matches this Grammar. An application can attach multiple ResultListeners to this Grammar. A ResultListener is removed with the removeResultListener method.

A ResultListener attached to a Grammar receives ResultEvents 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 occur 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.

Individual ResultEvents may be filtered with setResultMask.

Parameters:

listener - a ResultListener to attach to this Grammar

See Also:

removeResultListener, ResultEvent, RESULT_CREATED, GRAMMAR_FINALIZED, RESULT_ACCEPTED, RESULT_REJECTED, setResultMask

getActivationMode

int getActivationMode()

Returns the current activation mode for a Grammar. See the setActivationMode method for more detail on activation modes.

Returns:

the current activation mode

See Also:

setActivationMode, setActivatable, isActive

getReference

String getReference()

Gets the reference of this Grammar. A Grammar's reference must be unique for a GrammarManager.

Returns:

the Grammar reference

See Also:

GrammarManager

getGrammarManager

GrammarManager getGrammarManager()

Returns the GrammarManager that manages this Grammar.

Returns:

this Grammar's GrammarManager

isActive

boolean isActive()

Tests whether this Grammar is currently active for top-level recognition. When a Grammar is active at the top level, recognition matches incoming audio against the Grammar (and other active Grammars) to detect speech that matches the Grammar.

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

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 activatable property or activation mode of Grammars.
• An ENGINE_FOCUSED or ENGINE_DEFOCUSED event.

This method always returns false for a Grammar with ACTIVATION_INDIRECT mode. Additionally, GRAMMAR_ACTIVATED and GRAMMAR_DEACTIVATED events do not occur for Grammars with this activation mode.

Returns:

the current state of this Grammar being active at the top level

See Also:

setActivatable, setActivationMode, ACTIVATION_INDIRECT, ACTIVATION_FOCUS, ACTIVATION_MODAL, ACTIVATION_GLOBAL, GrammarEvent, GRAMMAR_ACTIVATED, GRAMMAR_DEACTIVATED, RecognizerEvent, CHANGES_COMMITTED, ENGINE_FOCUSED, ENGINE_DEFOCUSED

isActivatable

boolean isActivatable()

Returns the activatable property of this Grammar. The setActivatable method provides more details.

Returns:

the activatable property of this Grammar

See Also:

setActivatable

removeGrammarListener

void removeGrammarListener(GrammarListener listener)

Removes a GrammarListener from this Grammar.

Parameters:

listener - the GrammarListener to remove

See Also:

addGrammarListener

removeResultListener

void removeResultListener(ResultListener listener)

Removes a ResultListener from this Grammar.

Parameters:

listener - the ResultListener to remove

See Also:

addResultListener

setActivationMode

void setActivationMode(int mode)
                       throws IllegalArgumentException

Sets the activation mode of this Grammar. It may be set as ACTIVATION_INDIRECT, ACTIVATION_FOCUS, ACTIVATION_MODAL, or ACTIVATION_GLOBAL. The role of the activation mode in the activation conditions for a Grammar are described with each activation mode.

The default value for a Grammar loaded directly at the top level is ACTIVATION_FOCUS. The default value for a Grammar loaded indirectly by reference is ACTIVATION_INDIRECT. ACTIVATION_FOCUS is generally the preferred activation mode unless the user interface design dictates another choice.

For some GrammarManagers, changing the activation mode may be computationally expensive.

Parameters:

mode - the activation mode to set

Throws:

IllegalArgumentException - if mode is not a valid activation mode

See Also:

getActivationMode, ACTIVATION_INDIRECT, ACTIVATION_FOCUS, ACTIVATION_MODAL, ACTIVATION_GLOBAL, setActivatable, isActive, GrammarManager

setActivatable

void setActivatable(boolean activatable)

Sets the activatable property of this Grammar. Once a Grammar is made activatable and the activation conditions are met, it may be used to match incoming speech.

The activatable property of a Grammar can be tested by the isActivatable method. The isActive method tests if this Grammar is currently active for recognition. See that method for details.

An application may have zero, one or many Grammars activatable at the same time.

The activatable property should be set to true only when it is appropriate for a user to say something matching this Grammar. This can improve the recognition response time and accuracy.

Parameters:

activatable - to specify the activatable property

See Also:

isActivatable, isActive