javax.speech.recognition
Class RecognizerMode

Object
  EngineMode
      RecognizerMode

public class RecognizerMode
extends EngineMode

Provides information about a specific operating mode of a Recognizer. RecognizerMode extends EngineMode with features specific to Recognizers.

Like EngineMode, there are two types of RecognizerMode objects: those returned by the EngineManager or a Recognizer instance and those created by an application.

Engines return RecognizerMode objects from the EngineManager through the availableEngines method. They are also returned from a Recognizer instance with the getEngineMode method. For these RecognizerMode objects, all features will be set to non-null values.

Applications can create RecognizerMode objects using the appropriate constructor. Applications may leave any or all of the feature values null to indicate "don't care". Typically, application-created RecognizerModes are used to select an appropriate Recognizer for creation.

The EngineMode class describes additional detail on Engine selection.

Engine creation is described in the EngineManager class.

See Also:

Engine, Recognizer, getEngineMode, EngineMode, EngineManager, availableEngines, createEngine, SpeakerManager, SpeakerProfile

Field Summary

static RecognizerMode	DEFAULT RecognizerMode with all mode features set to "don't care" values.
static int	LARGE_SIZE Size constant representing a large vocabulary Recognizer.
static int	MEDIUM_SIZE Size constant representing a medium vocabulary Recognizer.
static int	SMALL_SIZE Size constant representing a small vocabulary Recognizer.
static int	VERY_LARGE_SIZE Size constant representing a very large vocabulary Recognizer.

Constructor Summary

RecognizerMode()
Constructs a RecognizerMode with all mode features set to "don't care" values.

RecognizerMode(SpeechLocale locale)
Constructs a RecognizerMode with a given SpeechLocale and other features set to "don't care" values.

RecognizerMode(String engineName, String modeName, Boolean running, Boolean supportsLetterToSound, Boolean supportsMarkup, Integer vocabSupport, SpeechLocale[] locales, SpeakerProfile[] profiles)
Constructs a RecognizerMode with all mode features specified.

Method Summary

boolean	equals(Object mode) Returns true if and only if the mode parameter is not null and has equal values of all mode features with this EngineMode.
SpeakerProfile[]	getSpeakerProfiles() Gets the SpeakerProfile list specified in this RecognizerMode.
SpeechLocale[]	getSpeechLocales() Gets the SpeechLocale list specified in this RecognizerMode.
Boolean	getSupportsMarkup() Gets the supports markup feature.
Integer	getVocabSupport() Gets the vocabulary support feature.
int	hashCode() Returns a hash code value for the object.
boolean	match(EngineMode require) Determines whether a RecognizerMode has all the features defined in the require object.
String	toString() Returns a String representation of this RecognizerMode.

Methods inherited from class EngineMode

getEngineName, getModeName, getRunning, getSupportsLetterToSound

Methods inherited from class Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

SMALL_SIZE

public static final int SMALL_SIZE

Size constant representing a small vocabulary Recognizer. See getVocabSupport for details.

See Also:

getVocabSupport, MEDIUM_SIZE, LARGE_SIZE, VERY_LARGE_SIZE, Constant Field Values

MEDIUM_SIZE

public static final int MEDIUM_SIZE

Size constant representing a medium vocabulary Recognizer. See getVocabSupport for details.

See Also:

getVocabSupport, SMALL_SIZE, LARGE_SIZE, VERY_LARGE_SIZE, Constant Field Values

LARGE_SIZE

public static final int LARGE_SIZE

Size constant representing a large vocabulary Recognizer. See getVocabSupport for details.

See Also:

getVocabSupport, SMALL_SIZE, MEDIUM_SIZE, VERY_LARGE_SIZE, Constant Field Values

VERY_LARGE_SIZE

public static final int VERY_LARGE_SIZE

Size constant representing a very large vocabulary Recognizer. See getVocabSupport for details.

See Also:

getVocabSupport, SMALL_SIZE, MEDIUM_SIZE, LARGE_SIZE, Constant Field Values

DEFAULT

public static final RecognizerMode DEFAULT

RecognizerMode with all mode features set to "don't care" values. This can be used to select a default Recognizer with EngineManager.createEngine. The documentation for the Recognizer interface includes an example of this.

See Also:

Recognizer, EngineManager, createEngine

Constructor Detail

RecognizerMode

public RecognizerMode()

Constructs a RecognizerMode with all mode features set to "don't care" values.

See Also:

DEFAULT

RecognizerMode

public RecognizerMode(SpeechLocale locale)

Constructs a RecognizerMode with a given SpeechLocale and other features set to "don't care" values.

This is a convenience constructor where the locale parameter is used to construct a SpeechLocale list of length one and other features are null.

Parameters:

locale - the desired SpeechLocale

See Also:

getSpeechLocales

RecognizerMode

public RecognizerMode(String engineName,
                      String modeName,
                      Boolean running,
                      Boolean supportsLetterToSound,
                      Boolean supportsMarkup,
                      Integer vocabSupport,
                      SpeechLocale[] locales,
                      SpeakerProfile[] profiles)

Constructs a RecognizerMode with all mode features specified.

The RecognizerMode is created with the specified values. Any parameter may be null to signify "don't care".

The SpeechLocale and SpeakerProfile lists specify a preference order.

Parameters:

engineName - the Engine name

modeName - the mode name

running - request for a running Engine

supportsLetterToSound - a flag specifying letter to sound support

supportsMarkup - a flag specifying markup support

vocabSupport - a value specifying the level of vocabulary support

locales - the SpeechLocale list specified

profiles - the SpeakerProfiles list specified

See Also:

getEngineName, getModeName, getRunning, getSupportsLetterToSound, getSupportsMarkup, getVocabSupport, getSpeechLocales, getSpeakerProfiles

Method Detail

equals

public boolean equals(Object mode)

Returns true if and only if the mode parameter is not null and has equal values of all mode features with this EngineMode.

Overrides:

equals in class EngineMode

Parameters:

mode - an EngineMode to compare

Returns:

true if mode equals this EngineMode

getSpeechLocales

public SpeechLocale[] getSpeechLocales()

Gets the SpeechLocale list specified in this RecognizerMode.

The list specifies a preference order. Each SpeechLocale for a Recognizer must have the language defined but the country may be undefined. The SpeechLocale variant is typically ignored.

In an application-generated RecognizerMode, a null value means "don't care". RecognizerModes returned by the EngineManager or Engines never return null.

The class description describes how features may be used to select an Engine or request information about a specific Engine.

Returns:

an array of SpeechLocales

getSpeakerProfiles

public SpeakerProfile[] getSpeakerProfiles()
                                    throws SecurityException

Gets the SpeakerProfile list specified in this RecognizerMode.

The SpeakerProfile list is the same as returned by the SpeakerManager.listKnownSpeakers if the associated Recognizer is ALLOCATED.

In an application-generated RecognizerMode, a null value means "don't care". An Engine-generated RecognizerMode returns a zero-length array if the SpeakerManager is not supported. Otherwise it returns a non-zero-length array with at least SpeakerProfile.DEFAULT.

The class description describes how features may be used to select an Engine or request information about a specific Engine.

Implementations return a subclass of this class that checks security settings and throws SecurityException if the application does not have permission. This class does not check security settings when used directly.

Returns:

SpeakerProfiles known to this mode

Throws:

SecurityException - if the application does not have permission

See Also:

SpeakerManager, listKnownSpeakers, SpeakerProfile.DEFAULT, Engine.ALLOCATED

Required permission:

javax.speech.recognition.SpeakerProfile

getSupportsMarkup

public Boolean getSupportsMarkup()

Gets the supports markup feature. An Engine that supports markup can properly interpret markup passed to the Engine (true). Some Engines do not expect to receive markup at all (false).

In an application-generated EngineMode, a null value means "don't care". An Engine-generated EngineMode never returns null.

The class description describes how features may be used to select an Engine or request information about a specific Engine.

When this feature is FALSE for a Recognizer, the createRuleGrammar methods and loadGrammar methods (with mediaType "application/srgs+xml") will throw an exception when called.

Overrides:

getSupportsMarkup in class EngineMode

Returns:

the value of the supports markup feature

See Also:

createRuleGrammar, loadGrammar

getVocabSupport

public Integer getVocabSupport()

Gets the vocabulary support feature. Values may be SMALL_SIZE, MEDIUM_SIZE, LARGE_SIZE, VERY_LARGE_SIZE, and null for don't care.

Vocabulary size support varies by engine implementation and platform capabilities. This feature gives an application an indication of the capabilities of a given Engine on a given platform.

The same Engine running on one platform may return a different value on another platform due to platform resource constraints. Also, two different implementations on the same platform may return different values due to differences in implementation resource requirements.

The values of SMALL_SIZE, MEDIUM_SIZE, LARGE_SIZE, and VERY_LARGE_SIZE correspond to vocabulary support for engines supporting approximately 10s, 100s, 1000s, and 10,000s of words. This is as measured for a nominal perplexity of 10.

When using this feature to request an Engine, the size supported may be larger than the size requested. An application may decide not to use such an Engine due to resource considerations. The getRunning feature may be used to determine a desired Engine is already running.

This value may be a fixed value for a given Engine on a platform or may take current resources into account.

In an application-generated RecognizerMode, a null value means "don't care". RecognizerModes returned by the EngineManager or Engines never return null.

The class description describes how features may be used to select an Engine or request information about a specific Engine.

Returns:

the value of the vocabulary support feature

See Also:

SMALL_SIZE, MEDIUM_SIZE, LARGE_SIZE, VERY_LARGE_SIZE, getVocabSupport, getRunning

hashCode

public int hashCode()

Returns a hash code value for the object. This method is supported for the benefit of hashtables.

Overrides:

hashCode in class EngineMode

Returns:

a hash code value for the object

match

public boolean match(EngineMode require)

Determines whether a RecognizerMode has all the features defined in the require object. Features in require which are null are not tested. All String comparisons are exact (case-sensitive).

The parameters are used as follows:

• If the require parameter is an EngineMode, then only the EngineMode features are tested.
• If the require parameter is a RecognizerMode (or sub-class) then the required SpeechLocales and required SpeakerProfiles are tested as follows. required SpeechLocales are tested as follows.
• Every SpeechLocale in require must be matched by a SpeechLocale in the tested object. A null value for SpeechLocales in require is ignored. Otherwise, all non-null Strings in the require SpeechLocale must match.
• Every SpeakerProfile in require must be matched by a SpeakerProfile in the tested object. A null value for SpeakerProfiles in require is ignored.

Note that it is possible to compare an EngineMode against a RecognizerMode and vice versa.

Overrides:

match in class EngineMode

Parameters:

require - an EngineMode to compare

Returns:

true if all defined features match

See Also:

getSpeechLocales, getSpeakerProfiles, getVocabSupport

toString

public String toString()

Returns a String representation of this RecognizerMode.

Overrides:

toString in class EngineMode

Returns:

a String representation of this RecognizerMode