javax.speech
Class EngineMode

Object
  EngineMode

Direct Known Subclasses:

RecognizerMode, SynthesizerMode

public abstract class EngineMode
extends Object

Provides information about a specific operating mode of a speech Engine.

The features defined in the EngineMode class apply to all speech Engines. Subclasses of EngineMode extend this class to define specialized features for corresponding subclasses of Engine.

The features of EngineMode are all Object references. All features are defined so that a null value means "don't care" when selecting an Engine or matching EngineMode. For example, a Boolean value for a feature means that its three values are true, false and null ("don't care").

EngineMode features follow the JavaBeans get and set property patterns.

Selection

There are two types of EngineMode objects: those created by the EngineManager or an Engine instance and those created by an application. Engine-created EngineMode objects are obtained from the EngineManager through the availableEngines method. They are also returned from an Engine with the getEngineMode method. For Engine-created EngineMode objects, all features will be set to non-null values.

Applications can create EngineMode objects using the appropriate constructor. Applications may leave any or all of the feature values null to indicate "don't care". Application-created EngineModes may be used to test the Engine-created EngineModes to select an appropriate Engine for creation.

The following example tests whether an Engine supports Swiss German:

 SynthesizerMode fromEngine = ...;
 // "de" is the ISO 639 language code for German
 // "CH" is the ISO 3166 country code for Switzerland
 // (see SpeechLocale for details)
 SynthesizerMode require = new SynthesizerMode(new SpeechLocale("de", "CH"));
 // test whether the engine mode supports Swiss German.
 if (fromEngine.match(require)) ...
 

An application can create a subclass of EngineMode and pass it to the createEngine method of EngineManager. In this common approach, the EngineManager performs the Engine selection. The following example shows the creation of a French Synthesizer:

 // Create a mode that requires French
 SynthesizerMode mode = new SynthesizerMode(new SpeechLocale("fr"));
 // Create a Synthesizer that supports French
 Synthesizer synth = EngineManager.createEngine(mode);
 

The EngineManager class provides additional examples of using EngineModes.

Applications that need advanced selection criterion will

1. Request an EngineMode list from availableEngines,
2. Select an EngineMode from the list using the methods of EngineList and EngineMode,
3. Pass the selected EngineMode to the createEngine method of EngineManager.

See Also:

Engine, getEngineMode, EngineManager, availableEngines, createEngine

Constructor Summary

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

EngineMode(String engineName, String modeName, Boolean running, Boolean supportsLetterToSound, Boolean supportsMarkup)
Constructs an EngineMode with the specified mode features.

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.
String	getEngineName() Gets the Engine name.
String	getModeName() Gets the mode name.
Boolean	getRunning() Gets the running feature for the resources underlying an Engine.
Boolean	getSupportsLetterToSound() Gets the letter to sound feature.
Boolean	getSupportsMarkup() Gets the supports markup feature.
int	hashCode() Returns a hash code value for the object.
boolean	match(EngineMode require) Determines whether an EngineMode has all the features defined in the require object.
String	toString() Returns a String representation of this EngineMode.

Methods inherited from class Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

EngineMode

public EngineMode()

Constructs an EngineMode with all mode features set to "don't care" values.

See Also:

EngineMode(String, String, Boolean, Boolean, Boolean)

EngineMode

public EngineMode(String engineName,
                  String modeName,
                  Boolean running,
                  Boolean supportsLetterToSound,
                  Boolean supportsMarkup)

Constructs an EngineMode with the specified mode features. Sets the parameters to the specified values. Any parameter may be null to signify "don't care".

Parameters:

engineName - an engine name

modeName - a mode name

running - a flag specifying a running engine

supportsLetterToSound - a flag specifying letter to sound support

supportsMarkup - a flag specifying markup support

See Also:

EngineMode(), getEngineName, getModeName, getRunning, getSupportsLetterToSound, getSupportsMarkup

Method Detail

getEngineName

public String getEngineName()

Gets the Engine name. The Engine name is a string that uniquely identifies a speech Engine (e.g., "Acme Recognizer"). It should be a unique String across companies and product lines.

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.

Returns:

the name of the Engine

getModeName

public String getModeName()

Gets the mode name. The mode name uniquely identifies a single mode of operation of a speech Engine (e.g., "Spanish Command and Control").

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.

Returns:

the value of the mode name feature

getRunning

public Boolean getRunning()

Gets the running feature for the resources underlying an Engine. An Engine is considered running (true) if allocate has been called and its resources have been allocated before or are in the process of being allocated. Once all Engine instances sharing the underlying resources call deallocate (DEALLOCATING_RESOURCES or DEALLOCATED states), the running feature becomes false.

This feature allows an application to request an Engine whose underlying resources have already been loaded. Using such an Engine can conserve resources.

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.

This method returns a Boolean value to support the "don't care" case and, therefore, the method name begins with "get" rather than "is".

Returns:

the value of the running feature

See Also:

allocate, deallocate, DEALLOCATING_RESOURCES, DEALLOCATED

getSupportsLetterToSound

public Boolean getSupportsLetterToSound()

Gets the letter to sound feature. An Engine that supports this feature includes the ability to generate pronunciations for missing words from Letter to Sound rules. Otherwise, the Engine is restricted to a particular vocabulary. The mode name from getModeName may contain additional information about the restricted vocabulary.

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.

This method returns a Boolean value to support the "don't care" case and, therefore, the method name begins with "get" rather than "is".

Returns:

the value of the letter to sound feature

See Also:

getModeName()

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.

Returns:

the value of the supports markup feature

See Also:

EngineMode(String, String, Boolean, Boolean, Boolean)

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 Object

Parameters:

mode - an EngineMode to compare

Returns:

true if mode equals this EngineMode

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 Object

Returns:

a hash code value for the object

match

public boolean match(EngineMode require)

Determines whether an EngineMode has all the features defined in the require object. Strings in require which are null are not tested ("don't care"). All String comparisons are exact (case-sensitive).

Parameters:

require - an EngineMode to compare

Returns:

true if all defined features match

toString

public String toString()

Returns a String representation of this EngineMode.

Overrides:

toString in class Object

Returns:

a String representation of this EngineMode