Overview | Package | Class | Tree | Index | Help | |||
PREV CLASS | NEXT CLASS | FRAMES | NO FRAMES | ||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.speech.Central
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:
null
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:
null
mode descriptor: the Central
class
selects a suitable engine for the default Locale
.
Central
class attempts to locate an engine with all application-specified
properties.
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:
Recognizer
or Synthesizer
has been created already and it has the required properties,
return a reference to it. (The last created engine is checked.)
EngineModeDesc.getRunning
is true
),
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.propertieswhere 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.AcmeEngineCentralThis 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 |
public static final Recognizer createRecognizer(EngineModeDesc require) throws IllegalArgumentException, EngineException, SecurityException
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.
require
- required engine properties or null
for
default engine selectionnull
if none is availableEngineModeDesc
do not refer to a known
engine or engine mode.RecognizerModeDesc
could not be properly created.createRecognizer
permissionpublic static final EngineList availableRecognizers(EngineModeDesc require) throws SecurityException
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.
require
- an EngineModeDesc
or RecognizerModeDesc
defining the required features of the mode descriptors in the returned listpublic static final Synthesizer createSynthesizer(EngineModeDesc require) throws IllegalArgumentException, EngineException
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.
require
- required engine properties or null
for
default engine selectionSynthesizer
matching the required properties or null
if none is availableEngineModeDesc
do not refer to a known
engine or engine mode.SynthesizerModeDesc
could not be properly created.public static final EngineList availableSynthesizers(EngineModeDesc require) throws SecurityException
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.
public static final void registerEngineCentral(String className) throws EngineException
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.
className
- name of a class that implements the EngineCentral
interface and provides access to an engine implementationclassName
is not a legal class or it does not
implement the EngineCentral
interfaceOverview | Package | Class | Tree | Index | Help | |||
PREV CLASS | NEXT CLASS | FRAMES | NO FRAMES | ||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
JavaTM Speech API
Copyright 1997-1998 Sun Microsystems, Inc. All rights reserved
Send comments to javaspeech-comments@sun.com