| Consts Inherited from Engine | |
| DEALLOCATED, ALLOCATING_RESOURCES, ALLOCATED, DEALLOCATING_RESOURCES, PAUSED, RESUMED | |
| Operations Inherited from Engine | |
| addEngineListener, removeEngineListener, allocate, deallocate, getAudioManager, getEngineModeDesc, getEngineProperties, getEngineState, getVocabManager, pause, resume, testEngineState, waitEngineState | |
| Operations Inherited from Bonobo::Unknown | |
| ref, unref, queryInterface | |
| Operation Details: |
Request notifications of all events for all Result
produced by this Recognizer. An application can
attach multiple ResultListeners to a
Recognizer. A listener is removed with the
removeResultListener method.
ResultListeners attached to a Recognizer
are the only ResultListeners to receive the
RESULT_CREATED event and all subsequent events.
ResultListener objects can also be attached to any
Grammar or to any Result. A listener
attached to the Grammar receives all events that
match that Grammar following a
GRAMMAR_FINALIZED event. A listener attached to a
Result receives all events for that result from the
time at which the listener is attached.
A ResultListener can be attached or removed in any
Engine state.
removeResultListener
Grammar#addResultListener
Result#addResultListener
ResultEvent#RESULT_CREATED
ResultEvent#GRAMMAR_FINALIZED
A ResultListener can be attached or removed in any
Engine state.
addResultListener
Result#removeResultListener
Grammar#removeResultListener
Commit changes to all loaded grammars and all changes of grammar
enabling since the last commitChanges. Because all
changes are applied atomically (all at once) the application does
not need to be concerned with intermediate states as it changes
grammar definitions and enabling.
The commitChanges call first checks that all the
loaded grammars are legal. If there are any problems with the
current definition of any RuleGrammar an exception
is thrown. Problems might include undefined rule name, illegal
recursion and so on (see the
Java Speech Grammar Format Specification
and the
GrammarSyntaxDetail
class documentation for details).
The commitChanges call is asynchronous (the changes
have not necessarily been committed when the call returns). When
the changes have been committed, a CHANGES_COMMITTED
event is issued to all RecognizerListeners and to
the GrammarListeners of all changed
Grammars.
Immediately following the CHANGES_COMMITTED event, a
GRAMMAR_CHANGES_COMMITTED GrammarEvent
is issued to the GrammarListeners of all changed
grammars.
The roll of commitChanges in
applying grammar changes
is described * in the documentation for the
Grammar interface. The
effect of the commitChanges method upon
Recognizer states is
described above.
The use of suspend with
commitChanges and their use for processing
asynchronous non-speech events
are also described above.
It is not an error to commitChanges when no grammars
have been changed. However, the Recognizer performs
state transitions in the same way as when grammars are changed.
The commitChanges method operates as defined when
the Recognizer is in the ALLOCATED
state. The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when the
engine reaches the ALLOCATED state. An error is
thrown if the Recognizer is in the
DEALLOCATED or DEALLOCATING_RESOURCES
state.
LISTENING
PROCESSING
SUSPENDED
suspend
RecognizerEvent#CHANGES_COMMITTED
Delete a RuleGrammar from the Recognizer.
The grammar deletion only takes effect when all
grammar changes are committed.
Recognizers may chose to ignore the deletion of built-in grammars.
The deleteRuleGrammar method operates as defined
when the Recognizer is in the ALLOCATED
state. The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when
the engine reaches the ALLOCATED state. An error is
thrown if the Recognizer is in the
DEALLOCATED or DEALLOCATING_RESOURCES
state.
commitChanges
RecognizerEvent#CHANGES_COMMITTED
If the Recognizer is in the PROCESSING
state (producing a Result), force the
Recognizer to immediately complete processing
of that result by finalizing it. It is acceptable behavior for a
Recognizer to automatically reject the current result.
The flush flag indicates whether the recognizer's
internally buffered audio should be processed before forcing the
finalize. Applications needing immediate cessation of recognition
should request a flush. If the force finalize is a response to a
user event (e.g. keyboard or mouse press) then the buffer is
typically not flushed because incoming speech from a user could
be lost.
The state behavior of the Recognizer is the same as
if the Result had been finalized because of
end-of-utterance. The Recognizer will transition
to the SUSPENDED state.
The forceFinalize method operates as defined when
the Recognizer is in the ALLOCATED state.
The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when the
engine reaches the ALLOCATED state. An error is
thrown if the Recognizer is in the
DEALLOCATED or DEALLOCATING_RESOURCES
state.
Return the DictationGrammar for a
Recognizer. Typically, the name
parameter is null to get access to the default
DictationGrammar for the Recognizer.
If the Recognizer does not support dictation, or if
it does have a DictationGrammar with the specified
name, then the method returns null.
An application can determine whether the Recognizer
supports dictation by calling the
isDictationGrammarSupported method of the
RecognizerModeDesc.
Note: the @name parameter is provided for future extension of the
API to allow more than one DictationGrammar
to be defined.
The getDictationGrammar method operates as defined
when the Recognizer is in the ALLOCATED
state. The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when the
engine reaches the ALLOCATED state. An error is thrown
if the Recognizer is in the DEALLOCATED
or DEALLOCATING_RESOURCES state.
DictationGrammar to be defined. DictationGrammar for a Recognizer.RecognizerModeDesc#isDictationGrammarSupported
Return the RecognizerProperties object. The method
returns exactly the same object as the
getEngineProperties method in the Engine
interface. However, with the getRecognizerProperties
method, an application does not need to cast the return value.
The RecognizerProperties are available in any state
of an Engine. However, changes only take effect
once an engine reaches the ALLOCATED state.
RecognizerProperties object for this engine. Engine#getEngineProperties
Get the RuleGrammar with the specified name. Returns
null if the grammar is not known to the Recognizer.
The getRuleGrammar method operates as defined when
the Recognizer is in the ALLOCATED
state. The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when the engine
reaches the ALLOCATED state. An error is thrown
if the Recognizer is in the DEALLOCATED
or DEALLOCATING_RESOURCES state.
RuleGrammar reference or null.
Return an object which provides management of the speakers of a
Recognizer. Returns null if the
Recognizer does not store speaker data - that is,
if it is a speaker-independent recognizer in which all speakers
are handled the same.
A getSpeakerManager returns successfully in any
state of a Recognizer. The
SpeakerManager methods that list speakers and
set the current speaker operate in any Recognizer
state but only take effect in the ALLOCATED state.
This allows an application can set the initial speaker prior
to allocating the engine. Other methods of the
SpeakerManager only operate in the
ALLOCATED state.
SpeakerManager for this Recognizer.
List the RuleGrammars known to the
Recognizer. Returns null if there are no grammars.
The listRuleGrammars method operates as defined
when the Recognizer is in the ALLOCATED
state. The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when
the engine reaches the ALLOCATED state. An error
is thrown if the Recognizer is in the
DEALLOCATED or DEALLOCATING_RESOURCES
state.
RuleGrammars known to the Recognizer.
Return an indication of whether this Recognizer
supports this grammar type.
Recognizer supports this grammar type.GRAMMAR_JSGF
GRAMMAR_SRGS
Create a RuleGrammar for the grammar formatted text
provided by the InputStream. If the grammar contained
in the Reader already exists, it is over-written.
The new grammar is used for recognition only after
changes are committed.
The caller is responsible for determining the character encoding of the formatted document. The character encoding information contained in the grammar format header is ignored.
The loadGrammar methods operate as defined when the
Recognizer is in the ALLOCATED state.
The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when the
engine reaches the ALLOCATED state. An error is
thrown if the Recognizer is in the
DEALLOCATED or DEALLOCATING_RESOURCES
state.
InputStream from which the grammar text is loaded.
RuleGrammar from grammar formatted text provided by the InputStream.loadGrammarFromURL
loadGrammarFromURLWithImports
Load a RuleGrammar and its imported grammars from
grammar formatted text from URLs or from system resources. The
loaded grammars are used for recognition only after
changes are committed.
The method returns a reference to the named
RuleGrammar. The method never returns
null since an exception is thrown if
grammarName cannot be loaded successfully.
The method attempts to load all imports of
grammarName, all imports of the imported grammars,
and so on. This recursive load stops when grammars are reached
that have already been loaded or when no more imports are found.
The intent is to ensure that every grammar needed to use the
named grammar is loaded.
For example, if we load grammar X, which imports grammar Y, which imports grammars A and B, then all four grammars are loaded. If any of the grammars are already loaded, then it and its imports are not reloaded.
Note that JSGF allows fully-qualified rulename references without a corresponding import statement. This method also attempts to load all grammars referenced by a fully-qualified rulename not already referenced and loaded by a corresponding import statement.
The advanced loadGrammarFromURLWithImports method provides more control of the loading process. This method is equivalent to:
loadGrammarFromURLWithImports(type, url, name, true, false, null);
(load imports, don't reload existing grammars, don't provide a list of loaded grammars.)
Locating Grammars
The context URL parameter is used as the first
parameter of the GrammarURL constructor.
The grammarName is converted to a grammar filename.
The conversion changes each each period character ('.') to a
file separator ('/'). The ".gram" suffix is appended to
identify the grammar file. The grammarName
"com.sun.numbers" becomes the filename "com/sun/numbers.gram".
This filename is used as the spec parameter in the URL constructor.
If the context is null, the grammars are searched for only as a system resource.
Reading Grammars
For each grammar it loads, the recognizer determines the file's character encoding by reading the JSGF header.
An exception is thrown if:
If an exception is thrown part way through loading a set of grammars the list of loaded grammars not explicitly available. The recognizer does not attempt to remove any partially loaded grammars.
The loadGrammar methods operate as defined when the
Recognizer is in the ALLOCATED state.
The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when the
engine reaches the ALLOCATED state. An error is
thrown if the Recognizer is in the
DEALLOCATED or DEALLOCATING_RESOURCES
state.
loadGrammarFromStream
loadGrammarFromURLWithImports
Load a RuleGrammar in grammar formatted text from a URL
or from system resources and optionally load its imports. This
method provide an additional control over whether grammars are
reloaded even if they have already been loaded, and allows caller
to receive a list of all grammars loaded by the
Recognizer. The loaded grammars are used for
recognition only after
changes are committed.
The three additional parameters of this method provide the
following extensions over the
loadGrammarFromURL
method:
loadImports: if false, the method only loads
the RuleGrammar specified by the name parameter.
If true, the method behaves like the
loadGrammarFromURL
method and recursively loads imported grammars.
reloadGrammars: if true, the method always
loads a RuleGrammar, even if it is already
loaded into the Recognizer. The previous
version of the grammar is overwritten. If false, the
method behaves like the
loadGrammarFromURL
method and does not load grammars that are already loaded,
or their imports.
loadedGrammars: if non-null, then as the
Recognizer loads any grammar it appends a
reference to that RuleGrammar to the vector.
grammarName are loaded plus their imports.Recognizer.RuleGrammar is appended as it is loaded. loadGrammarFromStream
loadGrammarFromURL
Create a new RuleGrammar for this recognizer with a
specified grammar name. The new grammar is used for recognition
only after
changes are committed.
The newRuleGrammar method operates as defined when
the Recognizer is in the ALLOCATED state.
The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when the
engine reaches the ALLOCATED state. An error is
thrown if the Recognizer is in the
DEALLOCATED or DEALLOCATING_RESOURCES
state.
RuleGrammar for this recognizer with a specified grammar name.
Create a new grammar by reading in a grammar stored in a
vendor-specific format. The data could have been stored using the
writeVendorGrammar method. The documentation for the
writeVendorGrammar method describes the use of vendor
grammar formats.
If a grammar of the same name already exists, it is over-written.
The readVendorGrammar method operates as defined
when the Recognizer is in the ALLOCATED
state. The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when the
engine reaches the ALLOCATED state. An error is
thrown if the Recognizer is in the
DEALLOCATED or DEALLOCATING_RESOURCES
state.
InputStream from which grammar is loaded Store a grammar in a vendor-specific format. The data can be reloaded at a future time by the readVendorGrammar method.
The output format will be specific to the type of recognizer that writes it. For example, data written by an Acme Command and Control Recognizer will be readable only by another Acme Command and Control Recognizer or by other recognizers that understand it's format. When portability is required, use the Java Speech Grammar Format.
Why is a Vendor grammar format useful? The recognizer can store information that makes reloading of the grammar faster than when JSGF is used. The recognizer may also store additional information (e.g. pronunciation, statistical and acoustic data) that improve recognition using this grammar.
The writeVendorGrammar method operates as defined
when the Recognizer is in the ALLOCATED
state. The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when the
engine reaches the ALLOCATED state. An error is
thrown if the Recognizer is in the
DEALLOCATED or DEALLOCATING_RESOURCES
state.
OutputStream where the grammar is written.Grammar to be written. Store a grammar in a vendor-specific format. The data can be
Read a Result object from a stream in a
vendor-specific format. The return value will include the
best-guess tokens, and may include N-best results, audio data,
timing data, training information and other data the is
optionally provided with a finalized Result.
The call returns null upon failure. Because result objects are stored in a vendor-specific format they cannot normally be loaded by incompatible recognizers.
The readVendorResult method operates as defined when
the Recognizer is in the ALLOCATED state.
The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when the
engine reaches the ALLOCATED state. An error is
thrown if the Recognizer is in the
DEALLOCATED or DEALLOCATING_RESOURCES
state.
InputStream from which Result is loaded.
Store a finalized Result object in a vendor-specific
format so that it can be re-loaded in a future session. All the
current information associated with the result is stored. If the
application will not need audio data or training information in
a future session, they should release that information (through
the FinalResult interface) before writing the result
to reduce storage requirements.
The writeVendorGrammar method operates as defined
when the Recognizer is in the ALLOCATED
state. The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when the
engine reaches the ALLOCATED state. An error is thrown
if the Recognizer is in the DEALLOCATED
or DEALLOCATING_RESOURCES state.
OutputStream where the result is written.Result to be written.
Release the speech focus from this Recognizer. A
FOCUS_LOST event is issued to
RecognizerListeners once the focus is released and
the Recognizer state changes from
FOCUS_OFF to FOCUS_ON.
Since one one application may have recognition focus at any time, applications should release focus whenever it is not required. Speech focus and other focus issues are discussed above in more detail.
It is not an error for an application to release focus for a
Recognizer that does not have speech focus.
Focus is implicitly released when a Recognizer is
deallocated.
The releaseFocus method operates as defined when the
Recognizer is in the ALLOCATED state.
The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when the
engine reaches the ALLOCATED state. An error is
thrown if the Recognizer is in the
DEALLOCATED or DEALLOCATING_RESOURCES
state.
requestFocus
FOCUS_OFF
RecognizerEvent#FOCUS_LOST
Engine#getEngineState
Request the speech focus for this Recognizer from
the underlying speech recognition engine. When the focus is
received, a FOCUS_GAINED event is issued to
RecognizerListeners and the Recognizer
changes state from FOCUS_ON to FOCUS_OFF.
Since one one application may have recognition focus at any time, applications should only request focus when confident that the user is speaking to that application. Speech focus and other focus issues are discussed above in more detail.
It is not an error for an application to request focus for a
Recognizer that already has speech focus.
The requestFocus method operates as defined when
the Recognizer is in the ALLOCATED
state. The call blocks if the Recognizer in
the ALLOCATING_RESOURCES state and completes when
the engine reaches the ALLOCATED state. An error
is thrown if the Recognizer is in the
DEALLOCATED or DEALLOCATING_RESOURCES
state.
releaseFocus
FOCUS_ON
RecognizerEvent#FOCUS_GAINED
Engine#getEngineState
Temporarily suspend recognition while the application updates
grammars prior to a commitChanges call. The
suspend call places the Recognizer
in the SUSPENDED state. While in that state the
incoming audio is buffered. The buffered audio is processed
after the recognizer has committed grammar changes and returned
to the LISTENING state.
The primary difference between the suspend and
pause methods is that audio is buffered while a
Recognizer is suspended whereas incoming audio is
ignored while in the PAUSED state. Also, the
SUSPENDED state should only be visited temporarily,
whereas a Recognizer can be PAUSED
indefinately.
The suspend method is asynchronous. When the call
returns, the recognizer is not necessarily suspended. The
getEngineState method, or the
RECOGNIZER_SUSPENDED events can be used to determine
when the recognizer is actually suspended.
The use of suspend with commitChanges
for handling atomic grammar changes and for handling asynchronous
events are described above.
Calls to suspend and commitChanges do
not nest. A single call to commitChanges can release
the Recognizer after multiple calls to
suspend.
The suspend method operates as defined when the
Recognizer is in the ALLOCATED state.
The call blocks if the Recognizer in the
ALLOCATING_RESOURCES state and completes when the
engine reaches the ALLOCATED state. An error is
thrown if the Recognizer is in the
DEALLOCATED or DEALLOCATING_RESOURCES
state.
commitChanges
SUSPENDED
RecognizerEvent#RECOGNIZER_SUSPENDED