Overview | Package | Class | Tree | Index | Help
PREV CLASS | NEXT CLASS	FRAMES | NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD	DETAIL: FIELD | CONSTR | METHOD

Class javax.speech.Central

java.lang.Object
  |
  +--javax.speech.Central

public class Central

extends Object

The Central class is the initial access point to all speech input and output capabilities. Central provides the ability to locate, select and create speech recognizers and speech synthesizers

Creating a Recognizer or Synthesizer

The createRecognizer and createSynthesizer methods are used to create speech engines. Both methods accept a single parameter that defines the required properties for the engine to be created. The parameter is an EngineModeDesc and may be one of the sub-classes: RecognizerModeDesc or SynthesizerModeDesc.

A mode descriptor defines a set of required properties for an engine. For example, a SynthesizerModeDesc can describe a Synthesizer for Swiss German that has a male voice. Similarly, a RecognizerModeDesc can describe a Recognizer that supports dictation for Japanese.

An application is responsible for determining its own functional requirements for speech input/output and providing an appropriate mode descriptor. There are three cases for mode descriptors:

1. null
2. Created by the application
3. Obtained from the availableRecognizers or availableSynthesizers methods of Central.

The mode descriptor is passed to the createRecognizer or createSynthesizer methods of Central to create a Recognizer or Synthesizer. The created engine matches all the engine properties in the mode descriptor passed to the create method. If no suitable speech engine is available, the create methods return null.

The create engine methods operate differently for the three cases. That is, engine selection depends upon the type of the mode descriptor:

1. null mode descriptor: the Central class selects a suitable engine for the default Locale.
2. Application-created mode descriptor: the Central class attempts to locate an engine with all application-specified properties.
3. Mode descriptor from availableRecognizers or availableSynthesizers: descriptors returned by these two methods identify a specific engine with a specific operating mode. Central creates an instance of that engine. (Note: these mode descriptors are distinguished because they implement the EngineCreate interface.)

Case 1: Example

    // Create a synthesizer for the default Locale
    Synthesizer synth = Central.createSynthesizer(null);
 

Case 2: Example

    // Create a dictation recognizer for British English
    // Note: the UK locale is English spoken in Britain
    RecognizerModeDesc desc = new RecognizerModeDesc(Locale.UK, Boolean.TRUE);
    Recognizer rec = Central.createRecognizer(desc);
 

Case 3: Example

    // Obtain a list of all German recognizers
    RecognizerModeDesc desc = new RecognizerModeDesc(Locale.GERMAN);
    EngineList list = Central.availableRecognizers(desc);
    // select amongst by other desired engine properties
    RecognizerModeDesc chosen = ...
    // create an engine from "chosen" - an engine-provided descriptor
    Recognizer rec = Central.createRecognizer(chosen);
 

Engine Selection Procedure: Cases 1 & 2

For cases 1 and 2 there is a defined procedure for selecting an engine to be created. (For case 3, the application can apply it's own selection procedure.)

Locale is treated specially in the selection to ensure that language is always considered when selecting an engine. If a locale is not provided, the default locale (java.util.Locale.getDefault) is used.

The selection procedure is:

1. If the locale is undefined add the language of the default locale to the required properties.
2. If a Recognizer or Synthesizer has been created already and it has the required properties, return a reference to it. (The last created engine is checked.)
3. Obtain a list of all recognizer or synthesizer modes that match the required properties.
4. Amongst the matching engines, give preference to:
   • A running engine (EngineModeDesc.getRunning is true),
   • An engine that matches the default locale's country.

When more than one engine is a legal match in the final step, the engines are ordered as returned by the availableRecognizers or availableSynthesizers method.

Security

Access to speech engines is restricted by Java's security system. This is to ensure that malicious applets don't use the speech 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. Individual implementations of Recognizer and Synthesizer may throw SecurityException on additional methods as required to protect a client from malicious applications and applets.

The SpeechPermission class defines the types of permission that can be granted or denied for applications. This permission system is based on the JDK 1.2 fine-grained security model.

Engine Registration

The Central 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 Central. There are two registration mechanisms: (1) add an EngineCentral class to a speech properties file, (2) temporarily register an engine by calling the registerEngineCentral method.

The speech properties files provide persistent registration of speech engines. When Central is first called, it looks for properties in two files:

    <user.home>/speech.properties
    <java.home>/lib/speech.properties 

where the <user.home> and <java.home> are the values obtained from the System properties object. (The '/' separator will vary across operating systems.) Engines identified in either properties file are made available through the methods of Central.

The property files must contain data in the format that is read by the load method of the Properties class. Central looks for properties of the form

    com.acme.recognizer.EngineCentral=com.acme.recognizer.AcmeEngineCentral 

This line is interpreted as "the EngineCentral object for the com.acme.recognizer engine is the class called com.acme.recognizer.AcmeEngineCentral. When it is first called, the Central class will attempt to create an instance of each EngineCentral object and will ensure that it implements the EngineCentral interface.

Note to engine providers: Central calls each EngineCentral for each call to availableRecognizers or availableSynthesizers and sometimes createRecognizer and createSynthesizer The results are not stored. The EngineCentral.createEngineList method should be reasonably efficient.

Method Summary

static EngineList	availableRecognizers(EngineModeDesc require) List EngineModeDesc objects for available recognition engine modes that match the required properties.
static EngineList	availableSynthesizers(EngineModeDesc require) List EngineModeDesc objects for available synthesis engine modes that match the required properties.
static Recognizer	createRecognizer(EngineModeDesc require) Create a Recognizer with specified required properties.
static Synthesizer	createSynthesizer(EngineModeDesc require) Create a Synthesizer with specified required properties.
static void	registerEngineCentral(String className) Register a speech engine with the Central class for use by the current application.

Methods inherited from class java.lang.Object

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

Method Detail

createRecognizer

public static final Recognizer createRecognizer(EngineModeDesc require)
                                                                 throws IllegalArgumentException,
                                                                        EngineException,
                                                                        SecurityException

Create a Recognizer with specified required properties. If there is no Recognizer with the required properties the method returns null.

The required properties defined in the input parameter may be provided as either an EngineModeDesc object or a RecognizerModeDesc object. The input parameter may also be null, in which case an engine is selected that supports the language of the default locale.

A non-null mode descriptor may be either application-created or a mode descriptor returned by the availableRecognizers method.

The mechanisms for creating a Recognizer are described above in detail.

Parameters:

require - required engine properties or null for default engine selection

Returns:

a recognizer matching the required properties or null if none is available

Throws:

IllegalArgumentException - if the properties of the EngineModeDesc do not refer to a known engine or engine mode.

EngineException - if the engine defined by this RecognizerModeDesc could not be properly created.

SecurityException - if the caller does not have createRecognizer permission

See Also:

availableRecognizers, RecognizerModeDesc

availableRecognizers

public static final EngineList availableRecognizers(EngineModeDesc require)
                                                         throws SecurityException

List EngineModeDesc objects for available recognition engine modes that match the required properties. If the require parameter is null, then all known recognizers are listed.

Returns a zero-length list if no engines are available or if no engines have the required properties. (The method never returns null).

The order of the EngineModeDesc objects in the list is partially defined. For each registered engine (technically, each registered EngineCentral object) the order of the descriptors is preserved. Thus, each installed speech engine should order its descriptor objects with the most useful modes first, for example, a mode that is already loaded and running on a desktop.

Parameters:

require - an EngineModeDesc or RecognizerModeDesc defining the required features of the mode descriptors in the returned list

Returns:

list of mode descriptors with the required properties

Throws:

SecurityException - if the caller does not have permission to use speech recognition

createSynthesizer

public static final Synthesizer createSynthesizer(EngineModeDesc require)
                                                                 throws IllegalArgumentException,
                                                                        EngineException

Create a Synthesizer with specified required properties. If there is no Synthesizer with the required properties the method returns null.

The required properties defined in the input parameter may be provided as either an EngineModeDesc object or a SynthesizerModeDesc object. The input parameter may also be null, in which case an engine is selected that supports the language of the default locale.

A non-null mode descriptor may be either application-created or a mode descriptor returned by the availableSynthesizers method.

The mechanisms for creating a Synthesizer are described above in detail.

Parameters:

require - required engine properties or null for default engine selection

Returns:

a Synthesizer matching the required properties or null if none is available

Throws:

IllegalArgumentException - if the properties of the EngineModeDesc do not refer to a known engine or engine mode.

EngineException - if the engine defined by this SynthesizerModeDesc could not be properly created.

See Also:

availableSynthesizers, SynthesizerModeDesc

availableSynthesizers

public static final EngineList availableSynthesizers(EngineModeDesc require)
                                                          throws SecurityException

List EngineModeDesc objects for available synthesis engine modes that match the required properties. If the require parameter is null, then all available known synthesizers are listed.

Returns an empty list (rather than null) if no engines are available or if no engines have the required properties.

The order of the EngineModeDesc objects in the list is partially defined. For each speech installation (technically, each registered EngineCentral object) the order of the descriptors is preserved. Thus, each installed speech engine should order its descriptor objects with the most useful modes first, for example, a mode that is already loaded and running on a desktop.

Throws:

SecurityException - if the caller does not have permission to use speech engines

registerEngineCentral

public static final void registerEngineCentral(String className)
                                       throws EngineException

Register a speech engine with the Central class for use by the current application. This call adds the specified class name to the list of EngineCentral objects. The registered engine is not stored persistently in the properties files. If className is already registered, the call has no effect.

The class identified by className must have an empty constructor.

Parameters:

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

Throws:

EngineException - if className is not a legal class or it does not implement the EngineCentral interface