javax.speech.recognition
Interface GrammarManager

public interface GrammarManager

Provides management of Grammars. A Grammar defines a set of words (technically known as tokens) and defines acceptable patterns in which the tokens may be arranged.

The methods in this interface operate on and reflect Grammar changes as they are requested. The Using Grammars section describes how a Recognizer uses Grammars, including how Grammar changes are incorporated (see Committing Changes).

Defining Grammars

The GrammarManager provides several approaches for creating and loading Grammars:

• createRuleGrammar: create a RuleGrammar programmatically
• loadGrammar: create a RuleGrammar from grammar text.

The Grammar Text section provides detail about the expected grammar text format.

Other important RuleGrammar functions include:

• deleteGrammar deletes a loaded Grammar.
• listGrammars returns an array of all Grammars loaded.

In addition to RuleGrammars that an application creates, some Recognizers have "built-in" Grammars. Built-in Grammars are automatically loaded into the Recognizer when the Recognizer is created and are accessible through the listGrammars method. Different Recognizers will have different built-in Grammars so applications should not rely upon built-in Grammars if they require portability.

Resolving References

Grammars may use standard URI conventions to refer to each other. The standard SRGS conventions for resolving any relative references apply (see "Resolving Relative URIs"). If any further resolution is required, information from the following two methods is used in priority order:

• RuleGrammar.getReference
• EngineProperties.getBase

A special "resource:" scheme may be used to force resolution with getResourceAsStream. This avoids unintended redirection of references that begin with "/" by EngineProperties.setBase. See that method for details.

A special "grammar:" scheme is recommended as an opaque reference in the case of String-based Grammars. This allows reference resolution between these types of Grammars. The HelloWorld example illustrates the use of this scheme.

Grammar Scope

Each GrammarManager object has a separate name-space. Applications should be aware that changes to a Grammar object affect all parts of the application that use that Grammar. However, if two separate applications reference different GrammarManagers and use a Grammar with the same name, they are effectively independent - changes by one application do not affect the operation of the other application.

Conditions for Operation

Where noted, standard Conditions for Operation apply. This means that a method operates as defined only when the associated Engine is in the ALLOCATED state and not DEALLOCATING_RESOURCES. The call blocks if the Engine is in the ALLOCATING_RESOURCES state and completes when the Engine reaches the ALLOCATED state. Otherwise, an exception is thrown for an Engine in the DEALLOCATING_RESOURCES or DEALLOCATED states.

See Also:

Grammar, RuleGrammar, Recognizer

Method Summary

void	addGrammarListener(GrammarListener listener) Requests notifications of GrammarEvents related to Grammars managed by this GrammarManager.
RuleGrammar	createRuleGrammar(String grammarReference, String rootName) Creates a new RuleGrammar for this GrammarManager with the specified grammarReference and rootName.
RuleGrammar	createRuleGrammar(String grammarReference, String rootName, SpeechLocale locale) Creates a new RuleGrammar for this GrammarManager with the specified grammarReference, rootName, and locale.
void	deleteGrammar(Grammar grammar) Deletes a Grammar from this GrammarManager.
Grammar	getGrammar(String grammarReference) Gets the Grammar with the specified grammarReference.
int	getGrammarMask() Gets the mask to filter GrammarEvents for added GrammarListeners.
Grammar[]	listGrammars() Lists the Grammars known to this GrammarManager.
Grammar	loadGrammar(String grammarReference, String mediaType) Loads a Grammar from a URI or named resource.
Grammar	loadGrammar(String grammarReference, String mediaType, boolean loadReferences, boolean reloadReferences, Vector loadedGrammars) Loads a Grammar from a URI or named resource with options for loading any referenced Grammars.
Grammar	loadGrammar(String grammarReference, String mediaType, InputStream byteStream, String encoding) Loads a Grammar from grammar text provided by an InputStream.
Grammar	loadGrammar(String grammarReference, String mediaType, Reader charStream) Loads a Grammar from grammar text provided by a Reader.
Grammar	loadGrammar(String grammarReference, String mediaType, String grammarText) Loads a RuleGrammar from grammar text provided as a String.
void	removeGrammarListener(GrammarListener listener) Removes a GrammarListener from this GrammarManager.
void	setGrammarMask(int mask) Sets the mask to filter GrammarEvents for added GrammarListeners.

Method Detail

addGrammarListener

void addGrammarListener(GrammarListener listener)

Requests notifications of GrammarEvents related to Grammars managed by this GrammarManager. An application can attach multiple listeners to a GrammarManager.

The setGrammarMask method controls masking of GrammarEvents.

Parameters:

listener - a listener for GrammarEvents

See Also:

removeGrammarListener, GrammarEvent, setGrammarMask

createRuleGrammar

RuleGrammar createRuleGrammar(String grammarReference,
                              String rootName)
                              throws IllegalArgumentException,
                                     EngineStateException,
                                     EngineException

Creates a new RuleGrammar for this GrammarManager with the specified grammarReference and rootName. This method is the same as calling createRuleGrammar(grammarReference, rootName, null). See that method for details.

Parameters:

grammarReference - the reference to the RuleGrammar to create

rootName - the name of the root Rule for this RuleGrammar

Returns:

a new RuleGrammar object

Throws:

EngineException - if RuleGrammars are not supported

IllegalArgumentException - if the RuleGrammar reference already exists

EngineStateException - when not in the standard Conditions for Operation

See Also:

createRuleGrammar(String, String, SpeechLocale)

Required Features:

getSupportsMarkup

createRuleGrammar

RuleGrammar createRuleGrammar(String grammarReference,
                              String rootName,
                              SpeechLocale locale)
                              throws IllegalArgumentException,
                                     EngineStateException,
                                     EngineException

Creates a new RuleGrammar for this GrammarManager with the specified grammarReference, rootName, and locale.

The grammarReference is the name used for this RuleGrammar. The grammarReference must not already exist for this GrammarManager.

A non-null rootName defines the root Rule and specifies where processing begins for this RuleGrammar. In this case, rootName is automatically made activatable with setActivatable(String, boolean). If the rootName is null, then the root Rule remains undefined and may be defined later with setRoot.

Rules must be added with the addRule method. These Rules, including the root Rule, may have PUBLIC scope to allow external reference by name.

The locale determines the default SpeechLocale used when interpreting the vocabulary within the RuleGrammar. It must match a SpeechLocale listed in the return from RecognizerMode.getSpeechLocales. For example,

((RecognizerMode) recognizer.getEngineMode()).getSpeechLocales().

The first SpeechLocale from that list is used as the default if locale is null.

An EngineException is thrown if RuleGrammars are not supported. The listGrammars method provides a list of all Grammars available.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

grammarReference - the reference to the RuleGrammar to create

rootName - the name of the root Rule for this RuleGrammar

locale - the SpeechLocale of the resulting RuleGrammar

Returns:

a new RuleGrammar object

Throws:

EngineException - if RuleGrammars are not supported

IllegalArgumentException - if the RuleGrammar reference already exists or an unexpected SpeechLocale is given

EngineStateException - when not in the standard Conditions for Operation

See Also:

createRuleGrammar, setActivatable, RuleGrammar.setActivatable(String, boolean), listGrammars, addRule, getReference, getRoot, setRoot, PUBLIC, resume, getSupportsMarkup, getSpeechLocales, GrammarEvent, GrammarException

Required Features:

getSupportsMarkup

deleteGrammar

void deleteGrammar(Grammar grammar)
                   throws IllegalArgumentException,
                          EngineStateException

Deletes a Grammar from this GrammarManager.

Deleted Grammars are no longer returned by listGrammars. GrammarManagers may chose to mark built-in Grammars as deleted rather than to actually delete them.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

grammar - the Grammar to delete

Throws:

IllegalArgumentException - if the Grammar is unknown

EngineStateException - when not in the standard Conditions for Operation

See Also:

listGrammars, getGrammar

getGrammar

Grammar getGrammar(String grammarReference)
                   throws EngineStateException

Gets the Grammar with the specified grammarReference. The grammarReference is a URI or named resource.

A Grammar is created with one of the createRuleGrammar or loadGrammar methods. Referenced Grammars may include "built-in" Grammars defined by the system, but portable applications should avoid these.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

grammarReference - a reference to a Grammar

Returns:

a Grammar or null if the referenced Grammar does not exist.

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

createRuleGrammar, loadGrammar, listGrammars, deleteGrammar, RuleGrammar

getGrammarMask

int getGrammarMask()

Gets the mask to filter GrammarEvents for added GrammarListeners.

See setGrammarMask for details.

The event mask can be set and retrieved in any Recognizer state.

Returns:

the current mask for GrammarEvents

See Also:

GrammarEvent, GrammarListener, setGrammarMask

listGrammars

Grammar[] listGrammars()
                       throws EngineStateException

Lists the Grammars known to this GrammarManager. A zero-length list is returned if there are none.

This method lists Grammars added by the application and "built-in" Grammars - Grammars defined by the system. Use the instanceof operator to determine the type of Grammar (for example, RuleGrammar) and which methods apply.

This method operates as defined when the standard Conditions for Operation apply.

Returns:

the Grammars associated with this GrammarManager

Throws:

EngineStateException - when not in the standard Conditions for Operation

See Also:

createRuleGrammar, loadGrammar, getGrammar, deleteGrammar, RuleGrammar

loadGrammar

Grammar loadGrammar(String grammarReference,
                    String mediaType)
                    throws GrammarException,
                           IllegalArgumentException,
                           IOException,
                           EngineStateException,
                           EngineException

Loads a Grammar from a URI or named resource. The grammarReference specifies a URI or named resource and the mediaType specifies the type of Grammar loaded.

If mediaType is null and cannot be determined, it defaults to "application/srgs+xml". For mediaType "application/srgs+xml", a RuleGrammar is returned. A GrammarException is thrown if the mediaType is not supported.

If a RuleGrammar is loaded and a root Rule is defined, then it is automatically made activatable with setActivatable(String, boolean).

If a Grammar corresponding to grammarReference already exists, it is over-written.

This method uses default parameters to control the loading of any referenced Grammars and is equivalent to:

loadGrammar(grammarReference, mediaType, true, false, null);

This means that any referenced Grammars are loaded, any existing referenced Grammars are not reloaded, and no list of loaded Grammars is indicated. See that method for detail.

This method attempts to load the referenced Grammar, all Grammars referenced from that Grammar, and so on. This recursive load stops when Grammars are reached that have already been loaded or when no more references are found. The intent is to ensure that every Grammar needed to use the referenced Grammar is loaded.

For example, if we load Grammar X, which references Grammar Y, which references Grammars A and B, then all four Grammars are loaded. If any of the Grammars referenced from X are already loaded, then they and their references are not reloaded.

The listGrammars method provides a list of all Grammars available.

An EngineException is thrown if the mediaType is "application/srgs+xml" and RuleGrammars are not supported.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

grammarReference - the URI or named resource to load

mediaType - the type of Grammar to load

Returns:

a Grammar object

Throws:

GrammarException - if the mediaType is not supported or if any loaded grammar text contains an error

IllegalArgumentException - if a problem is encountered accessing the grammarReference

IOException - if an I/O error occurs

EngineException - if RuleGrammars are not supported

EngineStateException - when not in the standard Conditions for Operation

See Also:

setActivatable, listGrammars, loadGrammar(String,String,boolean,boolean,Vector), setBase

Required Features:

getSupportsMarkup when mediaType is "application/srgs+xml", getSupportsLetterToSound when the vocabulary specified is not known

loadGrammar

Grammar loadGrammar(String grammarReference,
                    String mediaType,
                    boolean loadReferences,
                    boolean reloadReferences,
                    Vector loadedGrammars)
                    throws GrammarException,
                           IllegalArgumentException,
                           IOException,
                           EngineStateException,
                           EngineException

Loads a Grammar from a URI or named resource with options for loading any referenced Grammars. The grammarReference specifies a URI or named resource and the mediaType specifies the type of Grammar loaded.

If mediaType is null and cannot be determined, it defaults to "application/srgs+xml". For mediaType "application/srgs+xml", a RuleGrammar is returned. A GrammarException is thrown if the mediaType is not supported.

If a RuleGrammar is loaded and a root Rule is defined, then it is automatically made activatable with setActivatable(String, boolean).

If a Grammar corresponding to grammarReference already exists, it is over-written.

This method provides control over whether Grammars are recursively loaded, are reloaded even if they have already been loaded, and allows the caller to receive a list of all Grammars loaded by this method. The three additional parameters of this method provide the following extensions over the loadGrammar(String,String) method:

• loadReferences: If true, this method recursively loads referenced Grammars. If false, this method only loads the Grammar specified by the grammarReference parameter.
• reloadReferences: If true, this method always loads referenced Grammars, even if already loaded into the GrammarManager. Any previous versions of the Grammars are overwritten. If false, this method does not load referenced Grammars that are already loaded.
• loadedGrammars: if non-null, then the GrammarManager appends a reference to any loaded Grammars to this parameter.

RuleReferences within Grammars may be relative or fully-qualified. This method attempts to load all Grammars by properly resolving references.

A GrammarException is thrown if any syntax problems are found. Grammar loading ceases when a syntax problem is found and any such Grammar is ignored. However, any referenced Grammars loaded as a result of this method remain. The loadedGrammars parameter provides access to the list of Grammars actually loaded.

The listGrammars method provides a list of all Grammars available.

An EngineException is thrown if the mediaType is "application/srgs+xml" and RuleGrammars are not supported.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

grammarReference - the URI or named resource to load

mediaType - the type of Grammar to load

loadReferences - flag to indicate recursive loading of referenced Grammars

reloadReferences - flag to indicate reloading of referenced Grammars, even if they are already loaded

loadedGrammars - if non- null, a reference to each loaded RuleGrammar is appended

Returns:

the loaded Grammar

Throws:

GrammarException - if the mediaType is not supported or if any loaded grammar text contains an error

IllegalArgumentException - if a problem is encountered accessing the grammarReference

IOException - if an I/O error occurs

EngineException - if RuleGrammars are not supported

EngineStateException - when not in the standard Conditions for Operation

See Also:

setActivatable, listGrammars, loadGrammar(String, String), setBase

Required Features:

getSupportsMarkup when mediaType is "application/srgs+xml", getSupportsLetterToSound when the vocabulary specified is not known

loadGrammar

Grammar loadGrammar(String grammarReference,
                    String mediaType,
                    InputStream byteStream,
                    String encoding)
                    throws GrammarException,
                           IllegalArgumentException,
                           IOException,
                           EngineStateException,
                           EngineException

Loads a Grammar from grammar text provided by an InputStream. The application defines the grammarReference for this Grammar and the mediaType specifies the type of Grammar loaded. The encoding specifies how the InputStream is read.

If mediaType is null and cannot be determined, it defaults to "application/srgs+xml". For mediaType "application/srgs+xml", a RuleGrammar is returned. A GrammarException is thrown if the mediaType is not supported.

If encoding is null and cannot be determined, the default encoding for the mediaType is used. An IllegalArgumentException is thrown if the encoding is not supported.

If a RuleGrammar is loaded and a root Rule is defined, then it is automatically made activatable with setActivatable(String, boolean).

If a Grammar corresponding to grammarReference already exists, it is over-written.

This method does not load any referenced Grammars.

The listGrammars method provides a list of all Grammars available.

An EngineException is thrown if the mediaType is "application/srgs+xml" and RuleGrammars are not supported.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

grammarReference - the name of the RuleGrammar to load

mediaType - the type of Grammar to load

byteStream - the InputStream from which the grammar text is loaded

encoding - the encoding for the InputStream

Returns:

a Grammar object

Throws:

GrammarException - if the mediaType is not supported or if any loaded grammar text contains an error

IllegalArgumentException - if grammarReference is invalid

IOException - if an I/O error occurs

EngineStateException - when not in the standard Conditions for Operation

EngineException - if RuleGrammars are not supported

See Also:

listGrammars, setActivatable, setBase

Required Features:

getSupportsMarkup, getSupportsLetterToSound when the vocabulary specified is not known

loadGrammar

Grammar loadGrammar(String grammarReference,
                    String mediaType,
                    Reader charStream)
                    throws GrammarException,
                           IllegalArgumentException,
                           IOException,
                           EngineStateException,
                           EngineException

Loads a Grammar from grammar text provided by a Reader. The application defines the grammarReference for this Grammar and the mediaType specifies the type of Grammar loaded.

If mediaType is null and cannot be determined, it defaults to "application/srgs+xml". For mediaType "application/srgs+xml", a RuleGrammar is returned. A GrammarException is thrown if the mediaType is not supported.

If a RuleGrammar is loaded and a root Rule is defined, then it is automatically made activatable with setActivatable(String, boolean).

If a Grammar corresponding to grammarReference already exists, it is over-written.

This method does not load any referenced Grammars.

The listGrammars method provides a list of all Grammars available.

An EngineException is thrown if the mediaType is "application/srgs+xml" and RuleGrammars are not supported.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

grammarReference - the name of the RuleGrammar to load

mediaType - the type of Grammar to load

charStream - the Reader from which the grammar text is loaded

Returns:

a Grammar object

Throws:

GrammarException - if the mediaType is not supported or if any loaded grammar text contains an error

IllegalArgumentException - if grammarReference is invalid

IOException - if an I/O error occurs

EngineStateException - when not in the standard Conditions for Operation

EngineException - if RuleGrammars are not supported

See Also:

listGrammars, setActivatable, setBase

Required Features:

getSupportsMarkup, getSupportsLetterToSound when the vocabulary specified is not known

loadGrammar

Grammar loadGrammar(String grammarReference,
                    String mediaType,
                    String grammarText)
                    throws GrammarException,
                           IllegalArgumentException,
                           IOException,
                           EngineStateException,
                           EngineException

Loads a RuleGrammar from grammar text provided as a String. The application defines the grammarReference for this RuleGrammar and the mediaType specifies the type of Grammar loaded.

If mediaType is null and cannot be determined, it defaults to "application/srgs+xml". For mediaType "application/srgs+xml", a RuleGrammar is returned. A GrammarException is thrown if the mediaType is not supported.

If a RuleGrammar is loaded and a root Rule is defined, then it is automatically made activatable with setActivatable(String, boolean).

If a Grammar corresponding to grammarReference already exists, it is over-written.

This method does not load any referenced Grammars.

The listGrammars method provides a list of all Grammars available.

An EngineException is thrown if the mediaType is "application/srgs+xml" and RuleGrammars are not supported.

This method operates as defined when the standard Conditions for Operation apply.

Parameters:

grammarReference - the name of the RuleGrammar to load

mediaType - the type of Grammar to load

grammarText - the grammar text to load

Returns:

a Grammar object

Throws:

GrammarException - if the mediaType is not supported or if any loaded grammar text contains an error

IllegalArgumentException - if grammarReference is invalid

IOException - if an I/O error occurs

EngineStateException - when not in the standard Conditions for Operation

EngineException - if RuleGrammars are not supported

See Also:

setActivatable, listGrammars, setBase

Required Features:

getSupportsMarkup when mediaType is "application/srgs+xml", getSupportsLetterToSound when the vocabulary specified is not known

removeGrammarListener

void removeGrammarListener(GrammarListener listener)

Removes a GrammarListener from this GrammarManager.

Parameters:

listener - the GrammarListener to remove

See Also:

addGrammarListener

setGrammarMask

void setGrammarMask(int mask)

Sets the mask to filter GrammarEvents for added GrammarListeners.

It can improve efficiency to mask events that are not used. Events of interest can be seen by using the logical OR of the event constants defined in the GrammarEvent class. GrammarEvent.DEFAULT_MASK is the initial value.

The event mask can be set and retrieved in any Recognizer state. This method affects filtering of all attached GrammarListeners.

Parameters:

mask - the mask for GrammarEvents

See Also:

GrammarEvent, GrammarEvent.DEFAULT_MASK, GrammarListener, getGrammarMask