javax.speech
Class EngineManager

Object
  EngineManager

public class EngineManager
extends Object

The initial access point to all speech input and output capabilities. The EngineManager provides the ability to locate, select and create speech Engine instances.

Creating an Engine

The createEngine method creates speech Engines. It accepts a single parameter that defines the required features of the Engine to create. The parameter is a subclass of EngineMode corresponding to a subinterface of Engine.

The createEngine method operates differently depending on the type of the EngineMode subclass:

1. DEFAULT for an EngineMode subclass: the EngineManager selects a suitable Engine with default values.
2. Application-created EngineMode: the EngineManager attempts to locate an Engine with all application-specified features.
3. EngineMode selected from availableEngines: the EngineManager creates an instance of the specific Engine identified by the EngineMode. These EngineModes implement the EngineFactory interface.

Case 1: Example

 // Create a Synthesizer for the default speech locale
 Synthesizer synth = (Synthesizer)
     EngineManager.createEngine(SynthesizerMode.DEFAULT);
 

Case 2: Example

 // Create a Recognizer for British English
 // Use the language and country codes for English spoken in Great Britain
 RecognizerMode mode = new RecognizerMode(new SpeechLocale("en", "GB"));
 Recognizer rec = (Recognizer) EngineManager.createEngine(mode);
 

Case 3: Example

 // Obtain a list of all German recognizers
 RecognizerMode mode = new RecognizerMode(new SpeechLocale("de"));
 EngineList list = EngineManager.availableEngines(mode);
 // Filter by other desired engine features
 RecognizerMode chosen = ...
 // Create a Recognizer from "chosen" - 
 // an EngineManager-provided EngineMode
 Recognizer rec = (Recognizer) EngineManager.createEngine(chosen);
 

Engine Selection Procedure: Cases 1 and 2

For cases 1 and 2 there is a defined procedure for selecting an Engine to create. (For case 3, the application can apply its own selection procedure.)

SpeechLocale is treated specially in the selection to ensure that language is always considered when selecting an Engine. If a SpeechLocale is not provided, the default SpeechLocale (SpeechLocale.getDefault) is used.

The selection procedure is:

1. If the SpeechLocale not specified, use the language of the default SpeechLocale in the required features.
2. If a matching underlying Engine has been started already and it has the required features, return a new corresponding Engine instance that shares the previously allocated underlying resources. The running feature is true. Depending on the implementation, underlying Engines may be shared by multiple JVMs.
3. Obtain a list of all EngineModes that match the required features.
4. Amongst the matching Engines, give preference to:
   • A running Engine (EngineMode.getRunning is true),
   • An Engine that matches the default SpeechLocale's country.

When more than one Engine is a legal match in the final step, the Engines are preference ordered as returned by the availableEngines method.

Security

Access to speech Engines is restricted. This is to ensure that malicious applications do not use Engines inappropriately. For example, a Recognizer should not be usable without explicit permission because it could be used to monitor ("bug") an office.

A number of methods throughout the API throw SecurityException. Implementations of Engines may throw SecurityException as appropriate for the platform.

Engine Registration

The EngineManager class locates, selects and creates speech Engines from amongst a list of registered Engines. Thus, for an Engine to be used by Java applications, the Engine must register itself with EngineManager. There are two registration mechanisms:

1. adding an EngineListFactory class to the speech.properties resource,
2. temporarily registering an Engine by calling the registerEngineListFactory method.

The speech.properties resource provides persistent registration of speech Engine implementations. When EngineManager is first called, it reads the properties using the following:

EngineManager.class.getResourceAsStream("speech.properties")

Specifically, getResourceAsStream looks for /javax/speech/speech.properties as a resource. Engines identified are made available through the methods of EngineManager.

The speech.properties resource must contain data in the format that is read by the load method of the Properties class. EngineManager looks for properties of the form

 com.acme.recognizer.EngineListFactory=com.acme.recognizer.AcmeEngineListFactory
 

This line is interpreted as "the EngineListFactory object for the com.acme.recognizer Engine is the class called com.acme.recognizer.AcmeEngineListFactory." When it is first used, the EngineManager class will attempt to create an instance of each EngineListFactory object and will ensure that it implements the EngineListFactory interface.

The speech.properties resource may or may not be implemented as a file. The specific details depend on the platform and the implementation of getResourceAsStream. If changes for these properties are permitted, it may be through a user interface provided by the implementation rather than by direct editing of the values.

See Also:

RecognizerMode, SynthesizerMode, getResourceAsStream, EngineFactory, EngineListFactory

Method Summary

static EngineList	availableEngines(EngineMode required) Lists available EngineMode objects that match the required features.
static Engine	createEngine(EngineMode required) Creates an Engine with specified required features.
static String	getVersion() Returns the version of this API.
static void	registerEngineListFactory(String className) Registers a speech Engine implementation with the EngineManager for use by the current application.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

availableEngines

public static final EngineList availableEngines(EngineMode required)

Lists available EngineMode objects that match the required features. If the required parameter is null, then all EngineModes for known Engines are listed.

Returns a zero-length list if no Engines are available or if no Engines have the required features. This method never returns null.

The order of the EngineMode objects in the list is partially defined. For each registered Engine implementation (technically, each registered EngineListFactory object) the order of the EngineModes is preserved. Thus, each installed speech Engine implementation should order its EngineMode objects with the most useful ones first. For example, an EngineMode that is already loaded and running.

Parameters:

required - an EngineMode defining the required features or null for all

Returns:

list of EngineModes with the required features

See Also:

Engine, EngineMode

createEngine

public static final Engine createEngine(EngineMode required)
                                 throws IllegalArgumentException,
                                        EngineException

Creates an Engine with specified required features. If there is no Engine with the required features then this method returns null.

The required features defined in the input parameter are provided as an EngineMode object. Subinterfaces of Engine provide examples of how to create a particular kind of Engine. Subclasses of EngineMode provide a DEFAULT field to select an Engine that supports the language of the default SpeechLocale.

An EngineMode may be either created by an application, returned by the availableEngines method, or returned by an Engine instance with the getEngineMode method.

The mechanisms for creating an Engine are described in the preamble.

Parameters:

required - EngineMode features that are required

Returns:

an Engine matching the required features or null if none is available

Throws:

IllegalArgumentException - if the EngineMode is null

EngineException - if the Engine defined by the EngineMode could not be properly created

See Also:

availableEngines, EngineMode, getEngineMode

getVersion

public static String getVersion()

Returns the version of this API. The components are major.minor.build.revision. An example is "2.0.6.0".

Returns:

textual version information for this API.

registerEngineListFactory

public static final void registerEngineListFactory(String className)
                                            throws IllegalArgumentException,
                                                   SecurityException,
                                                   EngineException

Registers a speech Engine implementation with the EngineManager for use by the current application.

This method adds the specified className to the list of EngineListFactory objects. The registered Engine implementation is not stored persistently in speech.properties. If className is already registered, this method has no effect.

The class identified by className must have an empty constructor.

Note that not all devices support the dynamic class loading required by this method.

Parameters:

className - name of a class that implements the EngineListFactory interface and provides access to an Engine implementation

Throws:

IllegalArgumentException - if className is not a legal class or does not implement the EngineListFactory interface

EngineException - if this implementation does not support this method

SecurityException - if this method is not allowed by the calling application

See Also:

EngineListFactory

Required permission:

javax.speech.EngineManager.registerEngineListFactory