javax.telephony.media
Class ConfigSpec

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

All Implemented Interfaces:

ConfigSpecConstants, java.io.Serializable

public class ConfigSpec

extends java.lang.Object

implements ConfigSpecConstants, java.io.Serializable

Stores the information necessary to configure (or re-configure) a collection of resources. A ConfigSpec is essentially a read-only structure consisting of

• an Array of ResourceSpecs,
• a configuration timeout,
• a Dictionary of selection attributes and values,
• a Dictionary of initial parameter settings, and
• an Array of initial RTC settings.

A ConfigSpec object is an argument to the bind methods or configure() where it describes the requested configuration. A ConfigSpec is also the return value from getConfiguration() where it describes the current configuration.

A ConfigSpec used in configure() or the bind methods is obtained using the constructor, and is not modified thereafter. A ConfigSpec returned from getConfiguration() is inspected using one of the ConfigSpec field accessor methods.

Timeout:

Timeout indicates how long the application is willing to wait for the configuration process to complete. The implementation is allowed to wait up to timeout milliseconds for resources to become available. If the requested resources are not available at that time, configuration will fail, and the application can continue to interact with the caller using the previously configured resources.

Note: Timeout may be specified as ResourceConstants.FOREVER (or -1). Other negative values for timeout may generate an IllegalArgumentException.

Attributes:

When configuring a MediaGroup, the media provider may have choices regarding how and where the Resources are implemented. If the application is sensitive to the possible alternatives, it can specify the particular type of implemention required by supplying a Dictionary that defines a value for the attributes of interest.

ConfigSpec attributes are also used to specify processing options for bindAndConnect and related methods.

The defined attributes for a ConfigSpec are described in ConfigSpecConstants.

Pre-defined ConfigSpecs:

Two simple ConfigSpec objects are pre-defined:

basicConfig	requests the default SignalDetector, SignalGenerator, and alternating use of the default Player and Recorder
anyConfig	requests that no reconfiguration be attempted.

Note: ConfigSpec.anyConfig is identified by (ResourceSpec[] == null).
An empty ResourceSpec[], that is: (ResourceSpec[] = new ResourceSpec[]) indicates a configuration with no Resources.

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

FAQ: The ConfigSpec returned from getConfiguration is not the same ConfigSpec used in a previous configure. For example, the ResourceSpec[] in the returned ConfigSpec will contain descriptions of the Resources actually configured. Also, the Attributes of the ConfigSpec may contain additional attributes that were not mentioned in the ConfigSpec passed to configure.

Since:

JTAPI-1.3

See Also:

Serialized Form

Field Summary

static ConfigSpec	anyConfig A ConfigSpec instance that specifes that any configuration of Resources is acceptable.
static ConfigSpec	basicConfig A basic ConfigSpec.
static ConfigSpec	emptyConfig ConfigSpec for a MediaGroup with no Resources.

Fields inherited from interface javax.telephony.media.ConfigSpecConstants

a_AlertingTimeout, a_Arbitration, a_DeallocateOnIdle, a_LocalState, a_RemoteState, a_StopOnDisconnect, v_Alerting, v_Connected, v_FirstTalker, v_InProgress, v_LastTalker, v_MixTalkers

Constructor Summary

ConfigSpec(ResourceSpec[] specs, int timeout, java.util.Dictionary attributes, java.util.Dictionary parameters, RTC[] rtcs)
Constructor with full range of arguments.

ConfigSpec(java.lang.String configName, int timeout, ConfigSpec configSpec)
Copy a ConfigSpec and set the configName and timeout.

ConfigSpec(java.lang.String configName, int timeout, ResourceSpec[] specs, java.util.Dictionary attributes, java.util.Dictionary parameters, RTC[] rtcs)
Construct a ConfigSpec and set the configName.

Method Summary

java.util.Dictionary	getAttributes() Gets the Dictionary of attributes from this ConfigSpec.
java.lang.String	getConfigName() Return the String name of this ConfigSpec.
java.util.Dictionary	getParameters() Gets the Dictionary of parameters from this ConfigSpec.
ResourceSpec[]	getResourceSpecs() Retrieves the ResourceSpec[] from this ConfigSpec.
RTC[]	getRTC() Gets the persistant RTC[] for this ConfigSpec.
int	getTimeout() Returns the internal timeout value.
java.lang.String	toString() Elide package name, include getConfigName().

Methods inherited from class java.lang.Object

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

Field Detail

emptyConfig

public static final ConfigSpec emptyConfig

ConfigSpec for a MediaGroup with no Resources.

basicConfig

public static final ConfigSpec basicConfig

A basic ConfigSpec. This basic ConfigSpec waits 2 seconds to allocate ResourceSpec.basicAltPlayerRecorder, ResourceSpec.basicSignalDetector, and ResourceSpec.basicSignalGenerator.

anyConfig

public static final ConfigSpec anyConfig

A ConfigSpec instance that specifes that any configuration of Resources is acceptable. Informs the server that it should not do any reconfiguration.

ConfigSpec.anyConfig is identified by (ResourceSpec[] == null).

Constructor Detail

ConfigSpec

public ConfigSpec(java.lang.String configName,
                  int timeout,
                  ResourceSpec[] specs,
                  java.util.Dictionary attributes,
                  java.util.Dictionary parameters,
                  RTC[] rtcs)

Construct a ConfigSpec and set the configName.

The configName is a String name that identifies this configuration.

Parameters:

configName - a String to name this configSpec

timeout - int number of milliseconds to wait for resources. configure() should complete or abort in this time.

specs - an array of ResourceSpec

attributes - Dictionary of binding and selection attributes.

parameters - Dictionary of initial configuration parameters.

rtcs - Array of persistant RTCs.

ConfigSpec

public ConfigSpec(java.lang.String configName,
                  int timeout,
                  ConfigSpec configSpec)

Copy a ConfigSpec and set the configName and timeout.

The configName is a String name that identifies this configuration.

Parameters:

configName - a String to name this configSpec

timeout - int number of milliseconds to wait for resources. configure() should complete or abort in this time.

configSpec - use RessourceSpec[], Attributes, Parameters and RTC[] from here.

ConfigSpec

public ConfigSpec(ResourceSpec[] specs,
                  int timeout,
                  java.util.Dictionary attributes,
                  java.util.Dictionary parameters,
                  RTC[] rtcs)

Constructor with full range of arguments.

When specs is null, the ConfigSpec specifies that anyConfig configuration of Resources is acceptable.

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

Parameters:

specs - an array of ResourceSpec

timeout - int number of milliseconds to wait for resources. configure() should complete or abort in this time.

attributes - Dictionary of binding and selection attributes.

parameters - Dictionary of initial configuration parameters.

rtcs - Array of persistant RTCs.

Method Detail

toString

public java.lang.String toString()

Elide package name, include getConfigName().

Overrides:

toString in class java.lang.Object

Returns:

a String that identifies this ConfigSpec instance.

getConfigName

public java.lang.String getConfigName()

Return the String name of this ConfigSpec. May return null if no name is assigned.

Returns:

the String name of this ConfigSpec.

getTimeout

public int getTimeout()

Returns the internal timeout value.

Returns:

the int number of milliseconds to wait for resources.

getResourceSpecs

public ResourceSpec[] getResourceSpecs()

Retrieves the ResourceSpec[] from this ConfigSpec.

Returns:

the array of ResourceSpec objects.

getAttributes

public java.util.Dictionary getAttributes()

Gets the Dictionary of attributes from this ConfigSpec.

Returns:

the Dictionary of selection/configuration attributes.

getParameters

public java.util.Dictionary getParameters()

Gets the Dictionary of parameters from this ConfigSpec.

Returns:

the Dictionary of initial or current parameters

getRTC

public RTC[] getRTC()

Gets the persistant RTC[] for this ConfigSpec.

Returns:

the RTC[] of persistant RTCs.