javax.telephony.media
Class ResourceSpec

java.lang.Object
  |
  +--javax.telephony.media.ResourceSpec

Direct Known Subclasses:

ResourceSpec.Operator

public class ResourceSpec

extends java.lang.Object

Describes the attributes and other information for configuring Resources. A media Resource is described by three items:

• a Symbol that denotes the Resource Class,
• a Dictionary of selection attributes, and
• a Dictionary of the initial parameter settings.

Allocation Operators:

Alternatively, a ResourceSpec may be a collection of nested ResourceSpec objects related by an allocation operator. The allocation operators are: And, Alt, Or, Future, Add. Each operator is represented by an inner subclass of ResourceSpec.

Note: operator ResourceSpecs do not have a name, attributes or parameters.

Selection Attributes:

Each resource implementation is registered with a collection of Attributes that describe the features or capabilities of that implementation. Selection attributes specify the features or capabilities that an application expects or relies on. During configuration, only Resource implementations that have the requested Attributes are allocated and connected into the group.

For example, a Player that is capable of speed changing and that implements the speed changing API, RTCs, etc. would register the attribute: (Player.a_Speed = TRUE). An application that wants to use the speed change features during play() should request a Player with Attribute: (Player.a_Speed = TRUE) by including it in the selectionAttributes Dictionary when constructing the ResourceSpec. That is:

	Dictionary attrs = new Hashtable(17);
	attrs.put(Player.a_Speed, Boolean.TRUE);
 	new ResourceSpec( "SpeedPlayer", Player.v_Class, attrs, null);

The Attributes of a given resouce implementation are fixed ('final' as one would say in Java). If a resource is configured with (a_Speed=TRUE), then a_Speed will always report TRUE.

Attributes versus Parameters

In contrast, the amount of speed change to be invoked when the speed is changed is a variable controlled by the application. Application controllable settings are called parameters. Applications can set the parameters of a resource using MediaService.setParameters() or pre-set them during configuration by including them in the initialParameters of a ResourceSpec.

Note: This specification does not constrain how or whether the structured sub-components of a ResourceSpec are shared or copied between uses. Application developers are advised that there may be side-effects if an Array or Dictionary used in a ResourceSpec is subsequently modified. For example, it would be poor practice to modify the ResourceSpec[] that was used in the constructor to Alt(). Modifications should be made only to copies of such Arrays or Dictionaries.

Since:

JTAPI-1.3

Inner Class Summary

static class	ResourceSpec.Add Add each Resource, unless a compatible Resource is already configured.
static class	ResourceSpec.Alt All ResourceSpecs must be satisfied, but only needs to statisfy one at a time.
static class	ResourceSpec.And All ResourceSpecs must be satisfied, simultaneously.
static class	ResourceSpec.Future The given ResourceSpec[] specifies Resources that will be added in the future.
static class	ResourceSpec.Operator Represents the ResourceSpec operator nodes: And, Alt, Or, Add, Future.
static class	ResourceSpec.Or The given ResourceSpec[] is searched in order for a ResourceSpec that is satisfied.

Field Summary

static ResourceSpec	basicAltPlayerRecorder A ResourceSpec that provides alternating access to Player and Recorder.
static ResourceSpec	basicASR An ASR Resource with default parameters and attributes.
static ResourceSpec	basicPlayer A Player with default parameters and attributes.
static ResourceSpec	basicRecorder A Recorder with default parameters and attributes.
static ResourceSpec	basicSignalDetector A SignalDetector with default parameters and attributes.
static ResourceSpec	basicSignalGenerator A SignalGenerator with default parameters and attributes.
static ResourceSpec	none This ResourceSpec requests no actual resource.
static Symbol	op_Add Indicates that ResourceSpecs should be added to the current configuration.
static Symbol	op_Alt Indicates that ResourceSpecs are all required, but at different times.
static Symbol	op_And Indicates the all the given ResourceSpecs should be used.
static Symbol	op_Future Indicates the the given ResourcesSpecs maybe be added at some future time.
static Symbol	op_Or Indicates that any one given alternative ResourceSpecs may be used.

Constructor Summary

ResourceSpec(java.lang.Class resourceClass, java.util.Dictionary selectionAttributes, java.util.Dictionary initialParameters)
Deprecated. as of 1.4 use the resourceSymbol constructor

ResourceSpec(java.lang.String resourceClassName, java.util.Dictionary selectionAttributes, java.util.Dictionary initialParameters)
Deprecated. as of 1.4 use the resourceSymbol constructor

ResourceSpec(java.lang.String resSpecName, Symbol resourceSymbol, java.util.Dictionary selectionAttributes, java.util.Dictionary initialParameters)
Constructor with a name String, the resource Symbol, selection attributes and initial parameters.

Method Summary

java.util.Dictionary	getInitialParameters() Get the Dictionary of initial parameters.
java.lang.String	getName() Returns the String name assigned to this ResourceSpec.
java.lang.Class	getResourceClass() Deprecated. use getResourceSymbol()
Symbol	getResourceSymbol() Returns the Symbol for the ResourceClass of this ResourceSpec.
java.util.Dictionary	getSelectionAttributes() Get the Dictionary of additional selection attributes.
java.lang.String	toString() Elide package name, include getName().

Methods inherited from class java.lang.Object

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

Field Detail

basicPlayer

public static final ResourceSpec basicPlayer

A Player with default parameters and attributes.

basicRecorder

public static final ResourceSpec basicRecorder

A Recorder with default parameters and attributes.

basicSignalDetector

public static final ResourceSpec basicSignalDetector

A SignalDetector with default parameters and attributes.

basicSignalGenerator

public static final ResourceSpec basicSignalGenerator

A SignalGenerator with default parameters and attributes.

basicASR

public static final ResourceSpec basicASR

An ASR Resource with default parameters and attributes.

basicAltPlayerRecorder

public static final ResourceSpec basicAltPlayerRecorder

A ResourceSpec that provides alternating access to Player and Recorder.

none

public static final ResourceSpec none

This ResourceSpec requests no actual resource. As such, it is always satisfiable, by any server. This may be used to ensure that a ResourceSpec.Or always succeeds.

op_Add

public static final Symbol op_Add

Indicates that ResourceSpecs should be added to the current configuration.

op_Alt

public static final Symbol op_Alt

Indicates that ResourceSpecs are all required, but at different times.

op_And

public static final Symbol op_And

Indicates the all the given ResourceSpecs should be used.

op_Future

public static final Symbol op_Future

Indicates the the given ResourcesSpecs maybe be added at some future time.

op_Or

public static final Symbol op_Or

Indicates that any one given alternative ResourceSpecs may be used.

Constructor Detail

ResourceSpec

public ResourceSpec(java.lang.String resSpecName,
                    Symbol resourceSymbol,
                    java.util.Dictionary selectionAttributes,
                    java.util.Dictionary initialParameters)

Constructor with a name String, the resource Symbol, selection attributes and initial parameters.

The resSpecName is useful when processing alternative choices; the name helps the application recognize which choice was taken.

A resourceSymbol is defined for each standard Resource interface, typically with the field name v_Class. For example, Player.v_Class or ESymbol.Player_ResourceClass.

If the other arguments are null, they are treated the same as empty collections.

Parameters:

resSpecName - a String to identify this ResourceSpec.

resourceSymbol - the Symbol for the requested Resource interface.

selectionAttributes - a Dictionary containing required values for Attributes of the Resource implementation.

initialParameters - a Dictionary of initial parameter settings for this resource.

ResourceSpec

public ResourceSpec(java.lang.Class resourceClass,
                    java.util.Dictionary selectionAttributes,
                    java.util.Dictionary initialParameters)

Deprecated. as of 1.4 use the resourceSymbol constructor

Constructor using the resource class, selection attributes and initial parameters.

The resouceClass must be a valid Resource Class object. If the other arguments are null, they are treated the same as empty collections.

Deprecated because it is inadaquate/ambiguous whether to specify the simple/sync interface or the async interface. For example: Player.class or Async_Player.class

Parameters:

resourceClass - the Class object for the requested Resource interface.

selectionAttributes - a Dictionary containing required values for Attributes of the Resource implementation.

initialParameters - a Dictionary of initial parameter settings for this resource.

ResourceSpec

public ResourceSpec(java.lang.String resourceClassName,
                    java.util.Dictionary selectionAttributes,
                    java.util.Dictionary initialParameters)
             throws java.lang.ClassNotFoundException

Deprecated. as of 1.4 use the resourceSymbol constructor

Constructor using the resource name, selection attributes and initial parameters. This form of the constructor defers .class lookup until runtime.

The resourceClassName must identify a valid Resource class. The selectionAttributes and initialParameters may be null, which is treated as an empty Dictionary.

Parameters:

resourceClassName - the FQCN of the requested Resource interface.

selectionAttributes - a Dictionary containing required values for Attributes of the Resource implementation.

initialParameters - a Dictionary of initial parameter settings for this resource.

Throws:

java.lang.ClassNotFoundException - if class is not found

Method Detail

toString

public java.lang.String toString()

Elide package name, include getName().

Overrides:

toString in class java.lang.Object

Returns:

a String that identifies this ResourceSpec instance.

getName

public java.lang.String getName()

Returns the String name assigned to this ResourceSpec.

Returns:

the String name assigned to this ResourceSpec.

getResourceSymbol

public Symbol getResourceSymbol()

Returns the Symbol for the ResourceClass of this ResourceSpec.

Returns:

The Symbol representing the requested Resource interface.

getResourceClass

public java.lang.Class getResourceClass()

Deprecated. use getResourceSymbol()

Returns the Class of the media resource associated with this object.

Returns:

The Class object representing the requested Resource interface.

getSelectionAttributes

public java.util.Dictionary getSelectionAttributes()

Get the Dictionary of additional selection attributes.

Returns:

a Dictionary containing required values for Attributes of the Resource implementation.

getInitialParameters

public java.util.Dictionary getInitialParameters()

Get the Dictionary of initial parameters.

Returns:

a Dictionary of initial parameter settings for this resource.