Interface javax.speech.recognition.RuleGrammar


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

public abstract interface RuleGrammar
extends Grammar

RuleGrammar interface describes a Grammar that defines what users may say by a set rules. The rules may be defined as Rule objects that represent the rule in a data structure or defined in the Java Speech Grammar Format (JSGF).

All RuleGrammars are created and managed through the Recognizer interface. A RuleGrammar may be created with the newRuleGrammar method. A RuleGrammar is also created when JSGF text is loaded with the loadJSGF methods either from a Reader or from a URL.

A RuleGrammar contains the same information as a grammar definition in the Java Speech Grammar Format. That information includes:

The name of the grammar (inherited from Grammar interface),
A set of imports: each import references a single public rule of another RuleGrammar or all public rules of another RuleGrammar.
A set of defined rules: each definition is identified by a unique rulename (unique within the RuleGrammar), a boolean flag indicating whether the rule is public, and a Rule object that provides the logical expansion of the rule (how it spoken).

The set of imports and the rule definitions can be changed by applications. For any change to take effect the application must call the commitChanges method of the Recognizer.

A RuleGrammar can be printed in Java Speech Grammar Format using the toString method. Individual Rule objects can be converted to JSGF with their toString methods.

In JSGF a rulename is surrounded by angle brackets (e.g. <rulename>). The angle brackets are ignored in calls to the methods of a RuleGrammar - they may be included but are stripped automatically and are not included in rulenames returned by RuleGrammar methods.

The rules defined in a RuleGrammar are either public or private. A public rule may be:

Imported into other RuleGrammars,
Enabled for recognition,
Or both.

When a RuleGrammar is enabled and when the activation conditions are appropriate (as described in the documentation for Grammar) then the Grammar is activated and any of the public rules of the grammar may be spoken. The RuleGrammar interface extends the enable methods of the Grammar interface to allow individual rules to be enabled and disabled independently.

A public rule may reference private rules and imported rules. Only the top public rule needs to be enabled for it to be spoken. The referenced rules (local private or imported public rules) do not need to be enabled to be spoken as part of the enabled rule.

See Also:: Recognizer, Rule, Grammar, Java Speech Grammar Format

Method Summary
void	addImport(RuleName importName) Import all rules or a specified rule from another grammar.
void	deleteRule(String ruleName) Delete a rule from the grammar.
Rule	getRuleInternal(String ruleName) Returns a reference to a recognizer's internal rule object identified by a rule name.
Rule	getRule(String ruleName) Returns a `Rule` object for a specified rulename.
boolean	isEnabled() Returns true if any public rule of a `RuleGrammar` is enabled.
boolean	isEnabled(String ruleName) Test whether recognition of a specified rule of this `RuleGrammar` is enabled.
boolean	isRulePublic(String ruleName) Test whether a rule is public.
RuleName[]	listImports() Return a list of the current imports.
String[]	listRuleNames() List the names of all rules defined in this `RuleGrammar`.
RuleParse	parse(String text, String ruleName) Parse a `String` against a `RuleGrammar`.
RuleParse	parse(String[] tokens, String ruleName) Parse a sequence of tokens against a `RuleGrammar`.
RuleParse	parse(FinalRuleResult finalRuleResult, int nBest, String ruleName) Parse the nth best result of a `FinalRuleResult` against a `RuleGrammar`.
void	removeImport(RuleName importName) Remove an import.
RuleName	resolve(RuleName ruleName) Resolve a rulename reference within a `RuleGrammar` to a fully-qualified rulename.
Rule	ruleForJSGF(String JSGFText) Convert a `String` in partial Java Speech Grammar Format (JSGF) to a `Rule` object.
void	setEnabled(boolean enabled) Set the `enabled` property for a `RuleGrammar`.
void	setEnabled(String ruleName, boolean enabled) Set the enabled property for a specified public rule.
void	setEnabled(String[] ruleNames, boolean enabled) Set the enabled property for a set of public rules of a `RuleGrammar`.
void	setRule(String ruleName, Rule rule, boolean isPublic) Set a rule in the grammar either by creating a new rule or updating an existing rule.
String	toString() Return a string containing a specification for this `RuleGrammar` in Java Speech Grammar Format.

Method Detail

ruleForJSGF

public Rule ruleForJSGF(String JSGFText)
                                         throws GrammarException

Convert a String in partial Java Speech Grammar Format (JSGF) to a Rule object. The string can be any legal expansion from JSGF: i.e. anything that can appear on the right hand side of a JSGF rule definition. For example,

   Rule r = ruleGrammar.ruleForJSGF("[please] <action> all files");

Throws:: GrammarException - if the JSGF text contains any errors
See Also:: Java Speech Grammar Format

setRule

public void setRule(String ruleName,
                    Rule rule,
                    boolean isPublic)
            throws NullPointerException,
                   IllegalArgumentException

Set a rule in the grammar either by creating a new rule or updating an existing rule. The rule being set is identified by its "ruleName" and defined by the Rule object and its isPublic flag. The setRule method is equivalent to a rule definition in the Java Speech Grammar Format (JSGF).

The change in the RuleGrammar takes effect when grammar changes are committed.

The rule object represents the expansion of a JSGF definition (the right hand side). It may be a RuleToken, RuleName, RuleAlternatives, RuleSequence, RuleCount or RuleTag. Each of these 6 object types is an extension of the Rule object. (The rule object cannot be an instance of RuleParse which is also an extension of Rule.)

A rule is most easily created from Java Speech Grammar Format text using the ruleForJSGF method. e.g.

    gram.setRule(ruleName, gram.ruleForJSGF("open the <object>"), true);

The isPublic flag defines whether this rule may be enabled and active for recognition and/or imported into other rule grammars. It is equivalent to the public declaration in JSGF.

If the Rule object contains a fully-qualified reference to a rule of another RuleGrammar, an import is automatically generated for that rule if it is not already imported. A subsequent call to listImports will return that import statement.

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then they are automatically stripped.

The Rule object passed to the RuleGrammar is copied before being applied to recognizer. Thus, an application can modify and re-use a rule object without unexpected side-effects. Also, a different object will be returned by the getRule and getRuleInternal methods (although it will contain the same information).

Parameters:: ruleName - unique name of rule being defined (unique for this RuleGrammar); rule - logical expansion for the rulename; isPublic - true if this rule can be imported into other RuleGrammars or enabled
Throws:: IllegalArgumentException - if rule is not a legal instance of Rule; NullPointerException - if ruleName or rule are null
See Also:: ruleForJSGF, getRule, getRuleInternal, commitChanges, RuleAlternatives, RuleCount, RuleName, RuleSequence, RuleTag, RuleToken

getRule

public Rule getRule(String ruleName)

Returns a Rule object for a specified rulename. Returns null if the rule is unknown. The returned object is a copy of the recognizer's internal object so it can be modified in any way without affecting the recognizer. The setRule method should be called when a change to the returned rule object needs to be applied to the recognizer.

The Rule.toString method can be used to convert the return object to a printable String in Java Speech Grammar Format.

If there is a rule structure currently pending for a commitChanges that structure is returned. Otherwise, the current structure being used by the recognizer on incoming speech is returned.

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

If fast, read-only access to the rule object is required (e.g. in parsing), then the application may use getRuleInternal.

Parameters:: ruleName - the rulename to be returned
Returns:: the definition of ruleName or null
See Also:: setRule, getRuleInternal, commitChanges

getRuleInternal

public Rule getRuleInternal(String ruleName)

Returns a reference to a recognizer's internal rule object identified by a rule name. The application should never modify the returned object. This method is intented for use by parsers and other software that needs to quickly analyse a recognizer's grammars without modifying them (without the overhead of making copies, as required by getRule). If the returned object is ever modified in any way, getRule and setRule should be used.

Returns null if the rule is unknown.

If there is a Rule structure currently pending for a commitChanges that structure is returned. Otherwise, the current structure being used by the recognizer on incoming speech is returned.

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

See Also:: setRule, getRule, commitChanges

isRulePublic

public boolean isRulePublic(String ruleName)
                    throws IllegalArgumentException

Test whether a rule is public. Public rules may be enabled to be activated for recognition and/or may be imported into other RuleGrammars.

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

Parameters:: ruleName - the rulename being tested
Returns:: true if ruleName is public
Throws:: IllegalArgumentException - if ruleName is unknown

listRuleNames

public String[] listRuleNames()

List the names of all rules defined in this RuleGrammar. If any rules are pending deletion they are not listed (between a call to deleteRule and a commitChanges taking effect).

The returned names do not include the <> symbols.

deleteRule

public void deleteRule(String ruleName)
               throws IllegalArgumentException

Delete a rule from the grammar. The deletion only takes effect when grammar changes are next committed.

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

Parameters:: ruleName - name of the defined rule to be deleted
Throws:: IllegalArgumentException - if ruleName is unknown
See Also:: commitChanges

setEnabled

public void setEnabled(boolean enabled)

Set the enabled property for a RuleGrammar. When a grammar is enabled and when the activation conditions are appropriate, the RuleGrammar is activated for recognition and users may speak the commands/words/phrases defined by the grammar and results will be generated. The enabled state of a grammar can be tested by the isEnabled method. The activation state of a grammar can be tested by the isActive methods.

Recognizers can have multiple Grammars enabled and active at any time. A change in enabled status of the Grammar only takes effect when grammar changes are next committed. and the CHANGES_COMMITTED event is issued. The grammar is only activated once all the activation conditions are met (see documentation for Grammar).

All enabled rules of a RuleGrammar share the same ActivationMode. Thus, when a RuleGrammar is activated or deactivated for recognition, all the enabled rules of the RuleGrammar are activated or deactivated together.

This method is inherited from the Grammar interface. For a RuleGrammar, setEnabled(true) enables all public rules of the grammar. setEnabled(false) disables all public rules of the RuleGrammar. A RuleGrammar also provides setEnabled methods for enabling and disabling individual public rules or sets of public rules.

It is not an error to enable an enabled grammar or disable an disable grammar.

Specified by:: setEnabled in interface Grammar
See Also:: setEnabled(String, boolean), setEnabled(String[], boolean), isEnabled, setActivationMode

setEnabled

public void setEnabled(String ruleName,
                       boolean enabled)
               throws IllegalArgumentException

Set the enabled property for a specified public rule. This method behaves the same as the setEnabled(boolean) method except that it affects only a single public rule. The enabled state of other rules is unchanged.

Individual rules of a RuleGrammar may be individually enabled and disabled. Once any rule is enabled, the RuleGrammar is considered to be enabled. If all rules are disabled, then the RuleGrammar is considered disabled.

A change in the enabled property of a Rule or a RuleGrammar only takes effect when grammar changes are next committed.

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

Parameters:: ruleName - name of the rule to be enabled or disabled; enabled - true to enable ruleName, false to disable
Throws:: IllegalArgumentException - if ruleName is unknown or if it is a non-public rule
See Also:: setEnabled(boolean), setEnabled(String[], boolean), commitChanges

setEnabled

public void setEnabled(String[] ruleNames,
                       boolean enabled)
               throws IllegalArgumentException

Set the enabled property for a set of public rules of a RuleGrammar. This method behaves the same as the setEnabled(boolean) method except that it only affects a defined single public rule. This call does not affect the enabled state of other public rules of the RuleGrammar.

If any one or more rules are enabled, the RuleGrammar is considered to be enabled. If all rules are disabled, then the RuleGrammar is considered disabled.

A change in the enabled property of Rules or a RuleGrammar only takes effect when grammar changes are next committed.

If any rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

Parameters:: ruleNames - the set of rulenames to be enabled or disabled; enabled - true to enabled rulenames, false to disable
Throws:: IllegalArgumentException - if one or more ruleNames is unknown or if any is a non-public rule
See Also:: commitChanges

isEnabled

public boolean isEnabled()

Returns true if any public rule of a RuleGrammar is enabled.

Specified by:: isEnabled in interface Grammar
Returns:: true if RuleGrammar is enabled, otherwise false

isEnabled

public boolean isEnabled(String ruleName)
                 throws IllegalArgumentException

Test whether recognition of a specified rule of this RuleGrammar is enabled. If ruleName is null, the method is equivalent to isEnabled().

If the rule name contains both start/end angle brackets (e.g. "<ruleName>"), then the brackets are ignored.

Parameters:: ruleName - name of the rule being tested
Returns:: true if ruleName is enabled, otherwise false
Throws:: IllegalArgumentException - if ruleName is unknown or if it is a non-public rule

resolve

public RuleName resolve(RuleName ruleName)
                                         throws GrammarException

Resolve a rulename reference within a RuleGrammar to a fully-qualified rulename. The input rulename may be a simple rulename, qualified or fully-qualified. If the rulename cannot be resolved, the method returns null.

If the rulename being resolved is a local reference, the return value is a fully-qualified rulename with its grammar part being the name of this RuleGrammar.

Example: in a grammar that imports the rule <number> from the grammar "com.sun.examples", the following would return the fully-qualified rulename com.sun.examples.number.

   gram.resolve(new RuleName("number"));

If the input rulename is a fully-qualified rulename, then the method checks whether that rulename exists (and could therefore be successfully referenced in this RuleGrammar). If the rulename exists, then the retun value is the same as the input value, otherwise the method returns null.

Parameters:: ruleName - reference to rulename to be resolved
Returns:: fully-qualified reference to a rulename
Throws:: GrammarException - if an error is found in the definition of the RuleGrammar or if rulename is an ambiguous reference

addImport

public void addImport(RuleName importName)

Import all rules or a specified rule from another grammar. The RuleName should be in one these forms:

   <package.grammar.ruleName>
   <package.grammar.*>
   <grammar.ruleName>

<grammar.*> which are equivalent to the following declarations in the Java Speech Grammar Format.

   // import all public rules of a grammar
   import <package.grammar.*>        
   import <grammar.*>        

   // import a specific public rule name of a grammar
   import <package.grammar.ruleName>
   import <grammar.ruleName>

The forms without a package are only legal when the full grammar name does not include a package name.

The addImport takes effect when grammar changes are committed. When changes are committed, all imports must be resolvable. Specifically, every RuleGrammar listed in an import must exist, and every fully qualified rulename listed in an import must exist. If any ommissions are found, the commitChanges method throws an exception and the changes do not take effect.

It is not an exception to import a rule or set of rules and not reference them.

See Also:: listImports, removeImport, commitChanges

removeImport

public void removeImport(RuleName importName)
                 throws IllegalArgumentException

Remove an import. The name follows the format of addImport.

The change in imports only takes effect when grammar changes are committed.

Throws:: IllegalArgumentException - if importName is not currently imported
See Also:: addImport, commitChanges

listImports

public RuleName[] listImports()

Return a list of the current imports. Returns zero length array if no RuleGrammars are imported.

See Also:: addImport, removeImport

parse

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

Parse a String against a RuleGrammar. Parsing is the process of matching the text against the rules that are defined in the grammar. The text is tokenized as a Java Speech Grammar Format string (white-spacing and quotes are significant).

The string is parsed against the rule identified by ruleName, which may identify any defined rule of this rule grammar (public or private, enabled or disabled). If the ruleName is null, the string is parsed against all enabled rules of the grammar.

The method returns a RuleParse object. The documentation RuleParse describes how the parse structure and grammar structure correspond.

If parse fails, then the return value is null. To succeed, the parse must match the complete input string.

For some grammars and strings, multiple parses are legal. The parse method returns only one. It is not defined which of the legal parses should be returned. Development tools will help to analyse grammars for such ambiguities. Also grammar libraries can be used to parse results to check for these ambiguities.

Throws:: GrammarException - if an error is found in the definition of the RuleGrammar
See Also:: parse(String[], String), parse(FinalRuleResult, int, String)

parse

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

Parse a sequence of tokens against a RuleGrammar. In all other respects this parse method is equivalent to the parse(String text, String ruleName) method except that the string is pre-tokenized.

Throws:: GrammarException - if an error is found in the definition of the RuleGrammar
See Also:: parse(String, String), parse(FinalRuleResult, int, String)

parse

public RuleParse parse(FinalRuleResult finalRuleResult,
                       int nBest,
                       String ruleName)
                                        throws GrammarException

Parse the nth best result of a FinalRuleResult against a RuleGrammar. In other respects this parse method is equivalent to the parse(String text, String ruleName) method described above.

A rejected result (REJECTED state) is not guaranteed to parse. Also, if the RuleGrammar has been modified since the result was issued, parsing is not guaranteed to succeed.

Throws:: GrammarException - if an error is found in the definition of the RuleGrammar
See Also:: parse(String, String), parse(String[], String)

toString

public String toString()

Return a string containing a specification for this RuleGrammar in Java Speech Grammar Format. The string includes the grammar name declaration, import statements and all the rule definitions. When sending JSGF to a stream (e.g. a file) the application should prepend the header line with the appropriate character encoding information:

    #JSGF V1.0 encoding-format;

Overrides:: toString in class Object
See Also:: Java Speech Grammar Format


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