javax.speech
Interface EngineProperties

All Known Subinterfaces:

RecognizerProperties, SynthesizerProperties

public interface EngineProperties

Defines the run-time properties of an Engine. This interface is extended for each type of speech Engine.

Each property of an Engine has a set and get method. The method signatures follow the JavaBeans design patterns.

The run-time properties affect the behavior of a running Engine. Technically, properties affect Engines in the ALLOCATED state. Normally, property changes are made on an ALLOCATED Engine and take effect immediately or soon after the change request.

The EngineProperties object for an Engine is, however, available in all states of an Engine. Changes made to the properties of an Engine in the DEALLOCATED or the ALLOCATING_RESOURCES state take effect when the Engine next enters the ALLOCATED state. A typical scenario for setting the properties of a non-ALLOCATED Engine is to specify the initial state of the Engine. Setting Engine properties prior to allocation is desirable because changing them later can be computationally expensive.

When setting any Engine property:

• The Engine may choose to ignore or limit a change request either because it does not support changes in a property or because it is out of range.
• The Engine will apply the property change as soon as possible, but the change is not necessarily immediate. Thus, all set methods are asynchronous (call may return before the effect takes place).
• All properties of an Engine are bound properties - JavaBeans terminology for a property for which an event is issued when the property changes. An EnginePropertyListener can be attached to the EngineProperties object to receive an EnginePropertyEvent when a change takes effect.

For example, a call to the setPitch method of the SynthesizerProperties interface to change pitch from 120Hz to 200Hz might fail because the value is out of range. If it does succeed, the pitch change might be deferred until the Synthesizer can make the change by waiting to the end of the current word, sentence, paragraph or text object. When the change does take effect, an EnginePropertyEvent is issued to all attached listeners with the name of the changed property ("pitch"), the old value (120) and the new value (200).

Set calls take effect in the order in which they are received. If multiple changes are requested for a single property, a separate event is issued for each call, even if the multiple changes take place simultaneously.

The properties of an Engine are persistent across sessions where possible. It is the Engine's responsibility to store and restore the property settings. In multi-user and client-server environments the store/restore policy is at the discretion of the Engine.

The priority property is used with all Engine instances. It helps ensure desired interaction between applications. Priority may differ between trusted applications (such as those installed directly on the machine) and untrusted applications (such as those downloaded from the Web).

See Also:

Engine, EnginePropertyListener, EnginePropertyEvent, allocate, deallocate, ALLOCATED, ALLOCATING_RESOURCES, DEALLOCATING_RESOURCES, DEALLOCATED

Field Summary

static int	MAX_PRIORITY The maximum priority that an Engine instance can have.
static int	MAX_UNTRUSTED_PRIORITY The maximum priority that an untrusted Engine instance can have.
static int	MIN_PRIORITY The minimum priority that an Engine instance can have.
static int	NORM_TRUSTED_PRIORITY The default priority assigned to a trusted Engine instance.
static int	NORM_UNTRUSTED_PRIORITY The default priority assigned to an untrusted Engine instance.

Method Summary

void	addEnginePropertyListener(EnginePropertyListener listener) Adds an EnginePropertyListener to this EngineProperties object.
String	getBase() Gets the base property.
int	getPriority() Gets the priority property.
void	removeEnginePropertyListener(EnginePropertyListener listener) Removes an EnginePropertyListener from this EngineProperties object.
void	reset() Resets all properties to reasonable defaults for the Engine.
void	setBase(String uri) Sets the base property.
void	setPriority(int priority) Sets the priority property.

Field Detail

MIN_PRIORITY

static final int MIN_PRIORITY

The minimum priority that an Engine instance can have.

See Also:

setPriority, Constant Field Values

NORM_TRUSTED_PRIORITY

static final int NORM_TRUSTED_PRIORITY

The default priority assigned to a trusted Engine instance.

See Also:

setPriority, Constant Field Values

NORM_UNTRUSTED_PRIORITY

static final int NORM_UNTRUSTED_PRIORITY

The default priority assigned to an untrusted Engine instance.

See Also:

setPriority, Constant Field Values

MAX_UNTRUSTED_PRIORITY

static final int MAX_UNTRUSTED_PRIORITY

The maximum priority that an untrusted Engine instance can have.

See Also:

setPriority, Constant Field Values

MAX_PRIORITY

static final int MAX_PRIORITY

The maximum priority that an Engine instance can have.

See Also:

setPriority, Constant Field Values

Method Detail

addEnginePropertyListener

void addEnginePropertyListener(EnginePropertyListener listener)

Adds an EnginePropertyListener to this EngineProperties object. The listener is registered for all properties of the Engine.

An EnginePropertyEvent is fired in response to setting any EngineProperties property.

Parameters:

listener - the EnginePropertyListener to be added

See Also:

removeEnginePropertyListener

removeEnginePropertyListener

void removeEnginePropertyListener(EnginePropertyListener listener)

Removes an EnginePropertyListener from this EngineProperties object.

Parameters:

listener - the EnginePropertyListener to be removed

See Also:

addEnginePropertyListener

reset

void reset()

Resets all properties to reasonable defaults for the Engine. A property change event is issued for each Engine property that changes as the reset takes effect.

Note that any persistent changes made across sessions are lost.

getPriority

int getPriority()

Gets the priority property.

Returns:

the priority for this Engine instance

See Also:

setPriority

getBase

String getBase()

Gets the base property. This is the base location to resolve relative URLs against for this Engine instance.

The method setBase describes more detail.

Returns:

the base location for this Engine instance or null if not available

See Also:

setBase

setBase

void setBase(String uri)
             throws IllegalArgumentException

Sets the base property. This is the base location to resolve relative URLs against for this Engine instance.

This value applies to any relative URIs used in media locators or markup. When parsing markup, if a base tag is found and can be parsed, it will be used in conjunction with this base location for that markup.

The default value is "resource:/". This results in resolution, if needed, using getResourceAsStream. When available, the application's class loader is used the resource resolution context, but the rules for searching resources are profile and platform specific. In a MIDlet, for example, the associated jar file is used.

Setting this to null means that unresolved URIs will result in an exception or error event. This avoids unintended resolution by getResourceAsStream if that is not desired by an application.

Parameters:

uri - the desired base URI for this Engine

Throws:

IllegalArgumentException - if the uri is not valid

See Also:

getBase, getAudioManager, getResourceAsStream

setPriority

void setPriority(int priority)
                 throws IllegalArgumentException

Sets the priority property.

The priority values range between MIN_PRIORITY and MAX_PRIORITY. The priority used may be lower than the priority requested (rejected or limited). In this case, the return value will differ from the value requested.

Trusted applications may use the full range of priority values. Untrusted applications have a maximum of MAX_UNTRUSTED_PRIORITY, which is less than MAX_PRIORITY.

The default priority values for trusted and untrusted applications are NORM_TRUSTED_PRIORITY and NORM_UNTRUSTED_PRIORITY, respectively.

The priority property should be used with care to avoid starvation of other applications.

Changing the priority may be asynchronous, so any resulting focus change may not occur immediately.

The priority property may determine the order in which Engine instances interact. For example, focus gain and loss may be affected by priority.

Parameters:

priority - the priority for this Engine

Throws:

IllegalArgumentException - if the property value is out of range

See Also:

getPriority, EngineManager, addEnginePropertyListener, MIN_PRIORITY, NORM_TRUSTED_PRIORITY, NORM_UNTRUSTED_PRIORITY, MAX_UNTRUSTED_PRIORITY, MAX_PRIORITY