javax.speech.recognition
Interface RuleGrammar

All Superinterfaces:

Grammar

public interface RuleGrammar
extends Grammar

Defines a Grammar that specifies what users may say by a set of Rules. The Rules may be defined as Rule objects created programmatically or defined in grammar text (see below). The two representations are isomorphic and the toString method returns the grammar text representation of a RuleGrammar.

All RuleGrammars are created and managed through the GrammarManager interface. The createRuleGrammar method supports programmatically defined RuleGrammars and the loadGrammar methods can define RuleGrammars with grammar text.

Grammar Text

The grammar text format is defined by the Speech Recognition Grammar Specification (SRGS). It is used with the addRule(String) and GrammarManager.loadGrammar methods. Many of the RuleGrammar method descriptions use the element and attribute terminology borrowed from XML as used in SRGS. The SRGS specification contains definitions and examples.

The XML declaration is optional. The following default applies:

 <?xml version="1.0"?>
 

The DOCTYPE is also optional, but if included must reference the standard DOCTYPE and identifier as follows:

 <!DOCTYPE grammar PUBLIC "-//W3C//DTD GRAMMAR 1.0//EN"
                   "http://www.w3.org/TR/speech-grammar/grammar.dtd">
 

The grammar tag attributes for version and xmlns are required as follows:

 <grammar version='1.0' xmlns='http://www.w3.org/2001/06/grammar'>...</grammar>
 

Note that xmlns may also be a prefix for an attribute that indicates a grammar namespace other than the default. The xml:lang attribute may be included, but is otherwise inferred from the preferred SpeechLocale of the Recognizer returned by getSpeechLocales.

The recognition example includes a sample RuleGrammar. Programmatically defined RuleGrammars use the default attributes specified in getAttribute.

RuleGrammar Updates

Unless otherwise noted, methods operate on the current state of this RuleGrammar as it is updated. As with the Grammar interface, modifications take effect for recognition only after changes are committed with a call to resume. Changes are atomically committed or rejected with that call.

A RuleGrammar will be rejected when it is not properly defined. In that case, a GRAMMAR_CHANGES_REJECTED event will be issued to attached GrammarListeners. That event also includes a GrammarException to provide more detail about the problem. The method descriptions point out errors to avoid when defining or modifying a RuleGrammar.

See Also:

SRGS, Rule, Recognizer, createRuleGrammar, loadGrammar, resume, getSpeechLocales, GRAMMAR_CHANGES_REJECTED, GrammarListener, GrammarException

Field Summary

Fields inherited from interface Grammar

ACTIVATION_FOCUS, ACTIVATION_GLOBAL, ACTIVATION_INDIRECT, ACTIVATION_MODAL

Method Summary

void	addElement(String element) Specifies an element within this RuleGrammar.
void	addRule(Rule rule) Adds a Rule to this RuleGrammar.
void	addRule(String ruleText) Adds a Rule represented in grammar text to this RuleGrammar.
void	addRules(Rule[] rules) Adds an array of Rules to this RuleGrammar.
String	getAttribute(String attribute) Gets the value for the specified attribute in the grammar element.
String[]	getElements() Returns the elements added in this RuleGrammar.
String	getReference() Gets the reference of this Grammar.
String	getRoot() Gets the root Rule name for this RuleGrammar.
Rule	getRule(String ruleName) Returns a Rule object for the specified Rule name.
boolean	isActivatable() Returns the activatable property of this RuleGrammar.
boolean	isActivatable(String ruleName) Returns the activatable property of ruleName for this RuleGrammar.
String[]	listRuleNames() Lists the names of all Rules defined in this RuleGrammar.
RuleParse	parse(String[] tokens, String ruleName) Parses a sequence of tokens against this RuleGrammar.
RuleParse	parse(String text, String ruleName) Parses a String against this RuleGrammar.
void	removeElement(String element) Removes an element from this RuleGrammar.
void	removeRule(String ruleName) Removes a named Rule from this RuleGrammar.
RuleReference	resolve(RuleReference ruleReference) Resolves a RuleReference within this RuleGrammar.
void	setActivatable(boolean activatable) Sets the activatable property of this Grammar.
void	setActivatable(String ruleName, boolean activatable) Sets the activatable property for the specified ruleName.
void	setAttribute(String attribute, String value) Sets the value for the specified attribute in the grammar element.
void	setRoot(String rootName) Sets the root Rule name for this RuleGrammar.
String	toString() Returns a String containing a specification for this RuleGrammar in grammar text.

Methods inherited from interface Grammar

addGrammarListener, addResultListener, getActivationMode, getGrammarManager, isActive, removeGrammarListener, removeResultListener, setActivationMode

Method Detail

getAttribute

String getAttribute(String attribute)
                    throws IllegalArgumentException

Gets the value for the specified attribute in the grammar element.

The implementation default is returned if not defined or set.

Default values include:

• xmlns='http://www.w3.org/2001/06/grammar'
• version='1.0'
• xml:lang based on the current SpeechLocale.

Attribute values may be changed with the setAttribute method.

Parameters:

attribute - the desired attribute from the grammar element

Returns:

the value for the specified attribute

Throws:

IllegalArgumentException - if an illegal attribute is specified.

See Also:

setAttribute, getRoot

getElements

String[] getElements()

Returns the elements added in this RuleGrammar.

Because multiple elements may be added, this method returns an array of Strings. If the RuleGrammar contains no added elements, a zero length array is returned.

Returns:

the set of all elements added

See Also:

addElement, removeElement, getAttribute

removeRule

void removeRule(String ruleName)
                throws IllegalArgumentException

Removes a named Rule from this RuleGrammar.

If any part of this RuleGrammar uses or refers to ruleName, then the use of ruleName must be redefined or a new Rule must be defined for ruleName. This includes use of ruleName as the root or in a RuleReference. Otherwise, the error will be noted as described in the RuleGrammar Updates section.

Parameters:

ruleName - name of the Rule to be removed

Throws:

IllegalArgumentException - if ruleName does not correspond to a Rule when this method is called.

See Also:

setRoot, addRule, setAttribute, RuleReference

getRule

Rule getRule(String ruleName)

Returns a Rule object for the specified Rule name. Returns null if the Rule is unknown.

The addRule method is used to add Rules to this RuleGrammar.

The Rule.toString method can be used to convert the return object to a printable String in grammar text.

Parameters:

ruleName - the name of the Rule to find

Returns:

the Rule with the specified name or null

See Also:

addRule, Rule.toString()

getReference

String getReference()

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

Grammar references in RuleGrammars establish connections between Grammars. The reference for a RuleGrammar is set when it is created (either by loading grammar text or creating a new RuleGrammar).

Specified by:

getReference in interface Grammar

Returns:

the Grammar reference

See Also:

GrammarManager, RuleReference, createRuleGrammar, loadGrammar

getRoot

String getRoot()

Gets the root Rule name for this RuleGrammar. The root Rule name may be null if none was set.

Returns:

the name of the root Rule for this RuleGrammar

See Also:

setRoot, getAttribute, addRule, createRuleGrammar

setRoot

void setRoot(String rootName)

Sets the root Rule name for this RuleGrammar. The Rule identified by the root Rule name specifies the default Rule where processing begins for this RuleGrammar. This Rule may have PUBLIC scope to allow external reference by name.

The root Rule name may also be changed with the setAttribute method using the "root" attribute.

All PUBLIC scope Rules may be referenced from other Grammars. Specifying a root Rule allows implicit reference to a RuleGrammar: a RuleReference need only include the grammarReference.

All RuleGrammars should have a root Rule. However, ruleName may be null to effectively make the root for this RuleGrammar undefined.

Parameters:

rootName - the name of the root Rule for this RuleGrammar

See Also:

getRoot, addRule, removeRule, setAttribute, RuleReference, getGrammarReference, PUBLIC

listRuleNames

String[] listRuleNames()

Lists the names of all Rules defined in this RuleGrammar.

Returns a zero-length array if no Rules are defined.

Returns:

names of all Rules defined in this RuleGrammar

See Also:

removeRule, addRule

parse

RuleParse parse(String text,
                String ruleName)
                throws IllegalArgumentException,
                       GrammarException

Parses a String against this RuleGrammar. The text is first tokenized (white-space and quotes determine tokens) and then the String array version of parse is called. See that method for details.

Unlike other methods in this interface, this method operates with the last committed RuleGrammar Updates.

Parameters:

text - an input String defining tokens

ruleName - the name of the Rule from which the parse begins

Returns:

a RuleParse object corresponding to text or null

Throws:

IllegalArgumentException - if ruleName is non-null and is not activatable or is undefined

GrammarException - if an error is found in the definition of this RuleGrammar

See Also:

parse(String[], String)

parse

RuleParse parse(String[] tokens,
                String ruleName)
                throws IllegalArgumentException,
                       GrammarException

Parses a sequence of tokens against this RuleGrammar. Parsing is the process of matching the tokens against the Rules that are defined in the RuleGrammar.

The tokens are parsed against the Rule identified by ruleName, which must be activatable as described in isActivatable. However, if ruleName is null, then the tokens are parsed against all activatable ruleNames in the RuleGrammar.

This method returns a RuleParse object. The RuleParse relates parse structure to the corresponding grammar structure.

If the parse fails, then the return value is null. To succeed, the parse must match the complete sequence of tokens.

For some RuleGrammars and token sequences, multiple parses may result. The RuleParse returned by this method can represent more than one parse as described in RuleParse class. The most likely parse should be the first accessed if there is more than one. Development tools can help to analyze grammars for ambiguities that allow multiple parses.

Unlike other methods in this interface, this method operates with the last committed RuleGrammar Updates.

Parameters:

tokens - a sequence of tokens

ruleName - the name of the Rule from which the parse begins

Returns:

a RuleParse object corresponding to the tokens or null

Throws:

IllegalArgumentException - if ruleName is non-null and is not activatable or is undefined

GrammarException - if an error is found in the definition of this RuleGrammar

See Also:

parse(String, String), RuleParse, getRoot, getScope, isActivatable(String)

resolve

RuleReference resolve(RuleReference ruleReference)
                      throws GrammarException

Resolves a RuleReference within this RuleGrammar. If the RuleReference refers to a Rule within this RuleGrammar, a RuleReference is returned that includes the grammarReference. If not found, null is returned.

If the input RuleReference includes a grammarReference, it must agree with the grammarReference for this RuleGrammar. If the grammarReference is not defined or is relative, the grammarReference in the output RuleReference will be absolute.

The following example shows the result of resolving a RuleReference against a RuleGrammar loaded from a URI that contains a Rule named "number":

 String uri = "http://grammar.example.com/NumberGrammar.grxml";
 RuleGrammar ruleGrammar = (RuleGrammar)
     recognizer.getGrammarManager().loadGrammar(uri, "application/srgs+xml");
 RuleReference ruleReference =
     ruleGrammar.resolve(new RuleReference("number"));
 // now ruleReference.getGrammarReference is the URI
 

Parameters:

ruleReference - RuleReference to resolve

Returns:

a more fully specified RuleReference or null if not found

Throws:

GrammarException - if an error is found while executing this method

See Also:

getGrammarReference, getReference

setAttribute

void setAttribute(String attribute,
                  String value)
                  throws IllegalArgumentException

Sets the value for the specified attribute in the grammar element.

Possible attributes for the grammar element include: "version", "xmlns", "xml:lang", "mode", "root", "tag-format", "xml:base", "xmlns:xsi", and "xsi:schemaLocation".

Many of these values are optional and a default value will always be supplied. The getAttribute method lists the defaults.

The setRoot method contains more detail on setting the "root" attribute.

Parameters:

attribute - the desired attribute to set

value - the value for the desired attribute

Throws:

IllegalArgumentException - if the attribute or value is not supported.

See Also:

getAttribute, setRoot

addElement

void addElement(String element)
                throws GrammarException

Specifies an element within this RuleGrammar. Elements may be specified for "lexicon", "meta", "metadata", and "tag". Except for "metadata", these elements may be specified more than once. None of these are required.

If a lexicon is specified, the pronunciations affect only this RuleGrammar. The VocabularyManager does not return these pronunciations.

The following example shows how to add a meta element to a grammar:

 ruleGrammar.addElement("<meta name='author' content='Scott' />");
 

Parameters:

element - the element to add to this RuleGrammar

Throws:

GrammarException - if element is not supported or is malformed

See Also:

getElements, removeElement, setAttribute, VocabularyManager

removeElement

void removeElement(String element)

Removes an element from this RuleGrammar. The element parameter equals a previously added element.

If there is more than one such element, the first is removed. If none match, then none are removed and an exception is thrown.

Parameters:

element - the element to remove

Throws:

IllegalArgumentException - if element does not exist

See Also:

addElement, getElements, setAttribute, GrammarException, VocabularyManager

addRule

void addRule(Rule rule)

Adds a Rule to this RuleGrammar. If the RuleGrammar already contains a Rule with the same name, then it is replaced.

If the added Rule is PUBLIC scope, then it may be referenced by other RuleGrammars and/or become active for recognition. PRIVATE scope Rules may only be referenced by name within this RuleGrammar.

Parameters:

rule - the Rule to add to this RuleGrammar

Throws:

IllegalArgumentException - if Rule is null

See Also:

getRule, removeRule, PUBLIC, RuleReference

addRules

void addRules(Rule[] rules)

Adds an array of Rules to this RuleGrammar. This method adds each Rule to the RuleGrammar in the order in which they appear in the array. The addRule(Rule) method describes more detail.

Parameters:

rules - the Rules to add to this RuleGrammar

See Also:

addRule(Rule)

addRule

void addRule(String ruleText)
             throws GrammarException

Adds a Rule represented in grammar text to this RuleGrammar. Once the grammar text is correctly converted to a Rule, this method behaves the same as the addRule(Rule) method.

The following example adds a Rule from grammar text:

 ruleGrammar.addRule(
     "<rule id='object'>" +
         "<item repeat='0-1'>" +
             "<ruleref uri='#determiner'/>" +
         "</item>" +
         "<one-of>" +
             "<item>window</item>" +
             "<item>door</item>" +
         "</one-of>" +
     "</rule>";
 

This is equivalent to adding a Rule programmatically as follows:

 ruleGrammar.addRule(
     new Rule("object",
         new RuleSequence(new RuleComponent[] {
             new RuleCount(
                 new RuleReference("determiner"),
                 0, 1),
             new RuleAlternatives(
                 new String[] {"window", "door"})})));
 

The ruleText is interpreted in the context of this RuleGrammar. For example, the value of the xmlns and version attributes may be specified by the loaded grammar text, by setAttribute, or by the default attribute value in the case of a programmatically created RuleGrammar. The getAttribute method defines the default attributes.

Parameters:

ruleText - grammar text for a Rule to add

Throws:

GrammarException - if the grammar text contains any errors

See Also:

addRule(Rule), setAttribute, getAttribute

toString

String toString()

Returns a String containing a specification for this RuleGrammar in grammar text. The String includes the document information, the grammar element, the grammar attributes, and all contained elements, including all of the rule definitions.

Due to text formatting and normalization, the output of this method will most likely differ from the input RuleGrammar specified.

Overrides:

toString in class Object

Returns:

the grammar text for this RuleGrammar

isActivatable

boolean isActivatable()

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

Specified by:

isActivatable in interface Grammar

Returns:

the activatable property of the RuleGrammar

See Also:

setActivatable(boolean), isActivatable(String)

isActivatable

boolean isActivatable(String ruleName)

Returns the activatable property of ruleName for this RuleGrammar.

See the setActivatable method for details.

If ruleName does not exist (see getRule), then this method returns false.

Parameters:

ruleName - the name of the desired Rule

Returns:

true if ruleName is activatable, otherwise false

See Also:

isActivatable(), setActivatable(String, boolean), getRule

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.

A RuleGrammar is activatable by default when it is created by an application.

The RuleGrammar interface also provides the setActivatable(String, boolean) method to change the activatable property for individual Rules.

Any RuleReferences to this RuleGrammar from other RuleGrammars operate independently from the value of this property.

Specified by:

setActivatable in interface Grammar

Parameters:

activatable - flag to specify the activatable property

See Also:

isActivatable, isActive, setActivatable(String, boolean), setActivationMode, PUBLIC, getScope, RuleReference

setActivatable

void setActivatable(String ruleName,
                    boolean activatable)

Sets the activatable property for the specified ruleName. The ruleName must refer to the root Rule or a PUBLIC scope Rule.

When a ruleName is activatable, the containing RuleGrammar is activatable, and the activation conditions are met, it may be used to match incoming speech.

The default activatable property for ruleNames is false. The RuleGrammar factories in the GrammarManager automatically make the root ruleName activatable if it is defined. Otherwise, at least one ruleName in this RuleGrammar must be made activatable to allow a match with incoming speech.

As described for Grammars, the activatable property should be set to true only when it is appropriate for a user to say something matching the Rule identified by ruleName. This can improve the recognition response time and accuracy.

Any RuleReference that references this ruleName operates independently from the value of this property.

An error will be reported as described in the RuleGrammar Updates section if ruleName does not refer to a valid root or PUBLIC scope Rule when used in recognition.

Parameters:

ruleName - name of the Rule to which the activatable property applies

activatable - flag to specify the activatable property

See Also:

isActivatable(String), setActivatable(boolean), getRoot, PUBLIC, getScope, RuleReference