JSR-043: JTAPI-1.4

javax.telephony.media
Interface MediaService

All Superinterfaces:
MediaConstants, MediaServiceConstants
All Known Implementing Classes:
Base_MediaService, BasicMediaService

public interface MediaService
extends MediaServiceConstants

Defines the methods for binding and controlling the media processing resources associated with a Terminal.

Introduction:

A MediaService object represents the "service" that an application provides to a caller on the telephone. A media service encompasses the concepts of IVR and VoiceMail services and is similar to the concept of an "agent" as used in a call center environment. A MediaService plays the role of a "robotic agent" assigned to the Terminal, handling the Call that is active on that Terminal.

In contrast to the usual scenario for live-agents in a call center, in which the call is routed and connected to the agent's Terminal; in the JTAPI Media environment the MediaService application is brought to a Terminal on which the call is connected. This approach allows a series of MediaService applications to interact with the remote user without recourse to switching the call. Of course, using JTAPI Media does not preclude routing a call to other Addresses and Terminals.

Bind and Release:

When a MediaService instance is "brought to a Terminal", the MediaService is said to be bound to a collection of media processing resources that are connected to the media streams of that Terminal. A "collection of media processing resources that are connected to the media streams" [of a Terminal] is quite wordy, so we abbreviate and use the term MediaGroup. Therefore, one should properly say "the MediaService is bound to a MediaGroup". However, since that MediaGroup is [generally] connected to the streams of a Terminal, we sometimes say "the MediaService is bound to the Terminal".

Note: The proper phrase is preferred because the attributes and methods of the MediaGroup are accessible from the MediaService when it is bound to that MediaGroup. In contrast, the methods of the Terminal are only accessible from the Terminal, and that access is independent of whether the Terminal is otherwise associated with the MediaService.

When a MediaService is bound to a MediaGroup, the MediaService can control the media resources to play prompts and record messages, generate and detect tones or other communications signals for the Terminal.

When the MediaService is finished, it will release the MediaGroup. At that point, another MediaService may continue to process the call (in which case, that other MediaService gets bound to the MediaGroup), or the Connection to the Terminal may be dropped (possibly in conjunction with routing the call to some other Address).

Note: The bind and release methods presume some collection of administrative and call management support outside of the application. Throughout this document, this collection of service is refered to as the implementation or administrative or installation framework.

The framework may be as simple as routing all calls to a single application, or as complex as a geographically distributed call management system using SS7. Whatever the framework is, the implementation of the MediaService isolates an application from the details of that framework; so an application can be portable across a variety of simple or complex frameworks.

Bind methods:

There are several methods that bind a MediaService to a Terminal. They are collectively refered to as the bind methods. The methods all function similarly, and are differentiated primarily in how each determines the Terminal to bind.

The Terminal to bind (that is: the Terminal whose streams are connected to the MediaGroup to which the MediaService is bound) is determined for each method as follows:
Methodbinds to:
bindAndConnect(ConfigSpec,String,String) a Terminal connected to a new (outbound) Call
bindToServiceName(ConfigSpec,String) a Terminal connected to a Call that is routed to the named service
bindToCall(ConfigSpec,Call) a Terminal added to a specified Call
bindToTerminalName(ConfigSpec,String) a Terminal named by the specified String
bindToTerminal(ConfigSpec,Terminal) the specified Terminal object

Details of binding:

All the bind methods attempt to allocate media processing resources and connect them to the media streams associated with the Terminal. Again, the "media processing resources connected to the media streams" of a Terminal are called a MediaGroup.

The first argument to the bind methods, a ConfigSpec, specifies the particular media processing resources to be included in the MediaGroup and parameters that control how they are connected.

To configure means to find and connect the media processing resources that implement the interfaces and attributes specified in the ConfigSpec. When the configure is successful, the methods of the requested resource interfaces are available from the MediaService. Typically, the methods are implemented by the MediaGroup to which the MediaService is bound.

All the bind methods share these common semantics:

The bind methods block until the post-conditions are satisfied. The bind methods return the Connection to the Terminal, or null if there is no Connection.

Release:

A MediaService is generally bound to a MediaGroup only for the duration of a single call. When the MediaService is done servicing a call, the MediaGroup is released. When a MediaGroup is released the resources and UserDictionary are no longer available to this MediaService.

For all MediaService release methods:
pre-conditions: (isBound() && Delegation.isOwner())
post-conditions: (!isBound())

There are several forms of release: The simple release() indicates that this MediaService has completed its processing of the call, and control of the call passes to the previous owner. In the simple cases, ownership returns to the implementation or installation framework which is empowered and directed to disconnect the Connection and recycle any resources.

In contrast, releaseToService(String, int) indicates that further processing is expected, and the supplied disposition string determines which service (or Address) should continue the processing. The disposition strings are application specific, and are mapped to actual services or Addresses via implementation specific administrative interfaces.

If delegation is being used, then there are other alternatives. An application can use releaseToTag(returnTag) to return control to a previous owner. The returnTag is primarily designed to select which previous owner, but may also encode the status or cause for the return.

The method releaseToDestroy() is a simplified form of releaseToTag(String) which directs the call to the system framework with an indication that the call should be disconnected.

Disconnect processing:

When an active Connection to the bound Terminal is disconnected (that is, when it achieves the Connection.DISCONNECTED state), the method onDisconnected is invoked for each MediaServiceListener.

The effect of disconnect on media operations is controlled by the attribute a_StopOnDisconnect. When the Connection to the Terminal is disconnected and (a_StopOnDisconnect == TRUE), then

When all Connections to a Terminal are disconnected (or failed) some implementations may choose to recycle the resources. This feature is identified by the attribute a_DeallocateOnIdle. When there are no viable Connections to the Terminal and (a_DeallocateOnIdle == TRUE), then

Note: the MediaGroup is still bound, and the UserDictionary is still accessible until the MediaService is unbound by release.

Associated data:

There are several sets of information associated with a MediaService:
UserDictionary:
The UserDictionary is a Dictionary of key-value pairs associated with the MediaGroup to which the MediaService is bound. If the MediaGroup is released to another MediaService, the UserDictionary goes with the MediaGroup. This allows cooperating applications to easily share information. The UserDictionary is accessed using getUserValues, setUserValues and setUserDictionary.

The contents of the UserDictionary are defined and controlled by applications. This specification does not require the implementation/server to supply particular content for the UserDictionary. However, the framework or other applications are allowed to set values in the UserDictionary.

Parameters:
The Parameters of a MediaService are quantities that effect the control or status of the MediaGroup and its Resources. Resources may report various aspects of their state via parameters. Applications control or modify various aspects of a Resource by setting the appropriate Parameters. Parameters are accessed using getParameters and setParameters.
Attributes:
The Attributes of a MediaService describe generally immutable characteristics and capabilities of the MediaGroup. Attributes may be requested in a ConfigSpec, and attributes of a MediaService/MediaGroup can be accessed using getConfiguration() .getAttributes().
Configuration:
The Configuration of a MediaService is the attributes and parameters of the MediaGroup plus the collection of Resources allocated to the MediaGroup including the attributes and parameters of those Resources. The method getConfiguration() returns a ConfigSpec object that represents the current configuration of the MediaService. The ConfigSpec argument to configure(ConfigSpec) or any of the bind methods determines the configuration of the MediaService.

BasicMediaService:

MediaService is an interface; an implementation and constructor are available from the class BasicMediaService which implements MediaService and various Resource interfaces.

Since:
JTAPI-1.3

Fields inherited from interface javax.telephony.media.MediaServiceConstants
ev_BindAndConnect, ev_BindToCall, ev_BindToServiceName, ev_BindToTerminal, ev_BindToTerminalName, ev_Configure, ev_Connected, ev_DelegateToService, ev_Disconnected, ev_GetConfigSpec, ev_GetConfiguration, ev_GetParameters, ev_GetTerminal, ev_GetTerminalName, ev_GetUserValues, ev_GroupStop, ev_Release, ev_ReleaseDelegated, ev_ReleaseToDestroy, ev_ReleaseToService, ev_ReleaseToTag, ev_Retrieve, ev_Retrieved, ev_SetParameters, ev_SetUserDictionary, ev_SetUserValues, ev_TerminalIdle, ev_TriggerRTC
 
Fields inherited from interface javax.telephony.media.MediaConstants
e_OK, q_Duration, q_Standard, q_Stop
 
Method Summary
 void addListener(java.util.EventListener listener)
          Add a MediaListener to this MediaService.
 void addMediaListener(MediaListener listener)
          Deprecated. As of JTAPI 1.4, replaced by addListener(EventListener)
 void bindAndConnect(ConfigSpec configSpec, java.lang.String origAddr, java.lang.String dialDigits)
          Bind this MediaService to a new (outbound) Call.
 Connection bindToCall(ConfigSpec configSpec, Call call)
          Bind this MediaService to a particular Call.
 void bindToServiceName(ConfigSpec configSpec, java.lang.String serviceName)
          Bind this MediaService to a call directed to serviceName.
 void bindToTerminal(ConfigSpec configSpec, Terminal terminal)
          Bind this MediaService to a particular Terminal.
 void bindToTerminalName(ConfigSpec configSpec, java.lang.String terminalName)
          Bind this MediaService to a particular Terminal.
 void cancelBindRequest()
          Revoke previous bind or release request from this MediaService.
 void configure(ConfigSpec configSpec)
          Configure the bound MediaGroup according to the given configSpec.
 ConfigSpec getConfiguration()
          Return a ConfigSpec that describes the current configuration of this MediaService.
 MediaProvider getMediaProvider()
          Return the MediaProvider used by this MediaService.
 java.util.Dictionary getParameters(Symbol[] params)
          Get the value of various parameters from the MediaGroup bound to this MediaService.
 Terminal getTerminal()
          Return the Terminal associated with the MediaService.
 java.lang.String getTerminalName()
          Return the installation-specific String that identifies the Terminal to which this MediaService is bound.
 java.util.Dictionary getUserValues(Symbol[] keys)
          Creates and returns a new Dictionary that contains the UserDictionary values corresponding to a given set of keys.
 boolean isBound()
          Return true iff this MediaService is bound to a MediaGroup.
 void release()
          Release the MediaGroup from this MediaService using a NormalReturn.
 void releaseToDestroy()
          Release with an indication that the call is or should be disconnected and the MediaGroup destroyed.
 void releaseToService(java.lang.String disposition, int timeout)
          Release the MediaGroup from this MediaService with an indication that the call should to be processed by some other service.
 void releaseToTag(java.lang.String returnTag)
          Release MediaGroup from this MediaService to a previous owner.
 void removeListener(java.util.EventListener listener)
          Remove the MediaListener from this MediaService.
 void removeMediaListener(MediaListener listener)
          Deprecated. As of JTAPI 1.4, replaced by removeListener(EventListener)
 void setParameters(java.util.Dictionary params)
          Set the value of various parameters for the MediaGroup bound to this MediaService.
 void setUserDictionary(java.util.Dictionary newDict)
          Set the entire UserDictionary to a new collection of key-value pairs.
 void setUserValues(java.util.Dictionary dict)
          Set the values of several UserDictionary keys.
 void stop()
          Stop media operations on this MediaService.
 void triggerRTC(Symbol rtca)
          Deprecated. use transactional Resource commands.
 

Method Detail

getMediaProvider

public MediaProvider getMediaProvider()
Return the MediaProvider used by this MediaService.

A MediaService object is associated with a MediaProvider when it is constructed. See: BasicMediaService.BasicMediaService(String, String) This method returns the MediaProvider instance used by this MediaService object.

Returns:
the MediaProvider used by this MediaService.

bindToTerminalName

public void bindToTerminalName(ConfigSpec configSpec,
                               java.lang.String terminalName)
                        throws MediaBindException,
                               MediaConfigException
Bind this MediaService to a particular Terminal. This MediaService is bound to a MediaGroup that is configured as requested and connected to the named Terminal.

It is possible to bind to a Terminal that does not have any Connections. However, disconnect processing may prevent configuration of a MediaGroup unless there is an active Connection to the Terminal.

Throws a MediaConfigException if the Terminal cannot be connected to a MediaGroup, or if the MediaGroup cannot be configured as requested.

Parameters:
configSpec - a ConfigSpec describing the requested configuration
terminalName - a String that names a media capable Terminal
Throws:
MediaBindException - one of AlreadyBoundException, BindInProgressException, BindCancelledException.
MediaConfigException - if a MediaGroup can not be configured as requested

bindToTerminal

public void bindToTerminal(ConfigSpec configSpec,
                           Terminal terminal)
                    throws MediaBindException,
                           MediaConfigException
Bind this MediaService to a particular Terminal. This MediaService is bound to a MediaGroup that is configured as requested and connected to the given Terminal.

This is functionally equivalent to:
bindToTerminalName(configSpec, term.getName()),
but may perform better in some implementations.

Parameters:
configSpec - a ConfigSpec describing the requested configuration
terminal - a media-capable Terminal object
Throws:
MediaBindException - one of AlreadyBoundException, BindInProgressException, BindCancelledException.
MediaConfigException - if a MediaGroup can not be configured as requested.

bindToServiceName

public void bindToServiceName(ConfigSpec configSpec,
                              java.lang.String serviceName)
                       throws MediaBindException,
                              MediaConfigException
Bind this MediaService to a call directed to serviceName. Wait until this MediaService is bound to the MediaGroup of a Terminal connected to a Call that is directed to the given serviceName.

A call is directed to this serviceName when:

The mapping of disposition strings or call characteristics to service names is implementation specific, and is controlled by implementation specific administrative interfaces. For example:

Some frameworks may event take the initiative to assign a service name for each application media service to use. For those frameworks, consider using the RunnableMediaService interface.

This method does not complete unless the ConfigSpec is satisfied. If resources are not available when a call arrives, then the underlying call discrimination or routing process may leave the call unanswered until resources are available, or the call may be routed to some other service.

By default, the Connection of the Call to this Terminal is brought to the CONNECTED state before this method returns. The attribute a_LocalState can be set in the ConfigSpec to override the default.

Note: This function blocks, waiting for a call to be directed to the given serviceName. If cancelBindRequest() is subsequently invoked, this method unblocks throwing a BindCancelledException.

Parameters:
configSpec - a ConfigSpec describing the requested configuration
serviceName - the administrative name for this MediaService
Throws:
MediaBindException - one of AlreadyBoundException, BindInProgressException, BindCancelledException.
MediaConfigException - one of BadConfigSpecException, ResourceNotSupportedException
See Also:
a_LocalState, RunnableMediaService

bindToCall

public Connection bindToCall(ConfigSpec configSpec,
                             Call call)
                      throws MediaBindException,
                             MediaConfigException,
                             MediaCallException
Bind this MediaService to a particular Call. This MediaService is bound to the MediaGroup of a Terminal connected to the given Call. The effect is to provide media access to an existing Call. This typically creates a new Connection to the Call; which Connection is to the media enabled Terminal bound to this MediaService.

The Call must be in the ACTIVE state (or else attribute a_DealloateOnIdle must be FALSE). Otherwise, disconnect processing may interfere with allocating resources.

To create Connections and bind to a new Call, use bindAndConnect.

Parameters:
configSpec - a ConfigSpec describing the requested configuration.
call - a JTAPI Call object
Returns:
the Connection between the bound Terminal and the given Call.
Throws:
MediaBindException - one of AlreadyBoundException, BindInProgressException, BindCancelledException.
MediaConfigException - if a MediaGroup can not be configured as requested.
MediaCallException - encapsulates any call processing exceptions generated while trying to establish the new Call and Connection.

bindAndConnect

public void bindAndConnect(ConfigSpec configSpec,
                           java.lang.String origAddr,
                           java.lang.String dialDigits)
                    throws MediaBindException,
                           MediaConfigException,
                           MediaCallException
Bind this MediaService to a new (outbound) Call. This MediaService is bound to the MediaGroup of a Terminal connected to a new Call connected to the given Address.

This is a high-level function for making outbound calls while solving the problem of going offhook and finding an inbound call. (the phenomenon called glare).

This method (conceptually) does the following:

  1. Let term = an available media enabled Terminal at origAddr
  2. conn = call.connect(origAddr, term, dialDigits)[0];
  3. If inbound/glare then deliver that new Call as appropriate; goto 1.
  4. bindToTerminal(configSpec, term)
  5. return conn;

By default, the Connection to the remote party is brought to the Connection.CONNECTED state before this method returns. The attribute a_RemoteState can be set in the ConfigSpec to override that default.

Note: If origAddr is the empty string (""), then the implementation framework may choose a Terminal at any available Address.

Parameters:
configSpec - a ConfigSpec describing the requested configuration
origAddr - a String identifying the origination Address
dialDigits - a String identifying the destination Address
Throws:
MediaBindException - one of AlreadyBoundException, BindInProgressException, BindCancelledException.
MediaConfigException - if a MediaGroup can not be configured as requested.
MediaCallException - if the Call or Connections cannot be established.
See Also:
Call.connect(Terminal, Address, String)

cancelBindRequest

public void cancelBindRequest()
Revoke previous bind or release request from this MediaService.

This method is called from a thread that is not blocked in a bind method. This method terminates any outstanding bind or release request on this MediaService, causing that bind request to throw a BindCancelledException. If the outstanding bind request coincidentally completes normally then this method has no effect, and no error is signalled.

This method "succeeds" as soon as the cancel request is delivered to the MediaGroup/Provider implementation. This method is conceptually "one-way" and therefore safe to be invoked from within a Listener callback. The implemention of this method ensures that the threads and events do not deadlock as a result.

Implementation note: This can be arranged because this method has no return value, does not generate any exceptions, and has no provisions for "failing" once the invocation is delivered to the implementation. Therefore, the invoking thread does not need to wait for any response from the service provider implementation. If for any reason this method "fails" to unblock the outstanding request, the application may detect that (perhaps using a timeout) and retry this method.

If there is no outstanding bind request for this MediaService, no action is taken and no error is signalled; the assumption is that a bind just succeeded. Likewise, if the application times out and invokes a second cancelBindRequest, no harm is done.


isBound

public boolean isBound()
Return true iff this MediaService is bound to a MediaGroup.
Returns:
true iff this MediaService is bound to a MediaGroup.

release

public void release()
             throws NotBoundException,
                    MediaBindException
Release the MediaGroup from this MediaService using a NormalReturn. Indicates that this service has completed and has no interest in the further processing of the call.

For this and other MediaService release methods:
pre-conditions: (isBound() && isOwner())
post-conditions: (!isBound())

How the call is processed after release() depends on whether some other media service has delegated the call. If the call was delegated, then ownership of the call is returned to the MediaService which delegated the call. If the call was not delegated, then the system framework gets ownership and (typically) disconnects the call and releases the resources.

Note:To indicate that framework disconnect processing should be done even if the call is delegated, use the releaseToDestroy() method.

Note:To release this MediaService, but direct the further processing of the call to a specific new owner, an application may use: releaseToService(String, int).

Note:To release this MediaService, but direct the further processing of the call to a specific previous owner (which used delegateToService()), an application may use: releaseToTag(String).

Throws:
NotBoundException - if not currently bound to a MediaGroup
MediaBindException - one of: BindInProgressException or BindCancelledException.
BindInProgressException - if a bind or release is already in progress.
BindCancelledException - if interrupted by cancelBindRequest.

releaseToService

public void releaseToService(java.lang.String disposition,
                             int timeout)
                      throws NotBoundException,
                             MediaBindException,
                             MediaConfigException
Release the MediaGroup from this MediaService with an indication that the call should to be processed by some other service. The next service is determined by the disposition string.

Typically, the framework maps the disposition string to the serviceName of some other MediaService. The framework finds another MediaService that is waiting (in bindToServiceName) for that serviceName, configures the MediaGroup for that MediaService, binds the MediaGroup to that MediaService, and releases the MediaGroup from this MediaService.

If the given disposition string can not be mapped to a recognised serviceName, NoServiceAssignedException is thrown. If the disposition code is recognised, but no service suppliers are ready, this method waits for up to timeout milliseconds for a service to become ready and then throw NoServiceReadyException.

On completion, this MediaService is unbound from the MediaGroup. Further operations on this MediaService throw NotBoundException, until another MediaGroup is bound to this MediaService.

Note: The releasing media service can store additional information for the new owner by using setUserValues(Dictionary).

Implementation note: The disposition strings used by an application should be defined and documented as part of the external interface of the application. The installation and administration processes of a framework use that information to setup the mapping from disposition codes to the handling services. In some cases the framework may supply services to handle some disposition codes.

Note: Disposition strings beginning with "Special:" are reserved for standardized treatment. For example:
Special:Queue?address=<address> queue the call at the given address
Special:Transfer?address=<address> transfer the call to the given address
In these cases, the framework knows that a special service exists to implement the requested disposition. Additional information may be passed to the special service implementation using standard URL construction conventions.

Parameters:
disposition - a String that identifies the next MediaService.
timeout - milliseconds to wait for service to become ready.
Throws:
NotBoundException - if not currently bound to a MediaGroup
MediaBindException - one of: NoServiceAssignedException, NoServiceReadyException, BindInProgressException, BindCancelledException
NoServiceAssignedException - if disposition is not recognised or is not mapped to any serviceName.
NoServiceReadyException - if none of the MediaServices registered to disposition are ready and none become ready within timeout milliseconds.
BindInProgressException - if a bind or release is already in progress.
BindCancelledException - if interrupted by cancelBindRequest.
MediaConfigException - if the MediaGroup could not be configured for the recipient service.

releaseToTag

public void releaseToTag(java.lang.String returnTag)
                  throws MediaBindException
Release MediaGroup from this MediaService to a previous owner. Return ownership to the MediaService that called delegateToService() with catchTags that matche one of the given returnTags.

Some return tags have assigned usage:
Tag Name:Used for:
tag_NormalReturnsimple release()
tag_DestroyRequestreleaseToDestroy
tag_RemoveSessionreleaseToRemove
null or ""NormalReturn

Note: each previous owner is checked, from most recent to oldest. If the previous owner does not catch the return tag, then delegateToService completes with qualifier q_Released, and that MediaService !isBound(). If the previous owner does catch the return tag, then it becomes the new owner: delegateToService completes with qualifier q_Returned and that MediaService isBound() and isOwner().

Note: the returnTag conceptually specifies a single tag, indicating the terminatation status of this MediaService. Each 'catcher' should catch all that apply, using catchTags. However, to enable interoperability with applications that may be catching disjoint names, the MediaService invoking returnToTag is allowed to supply a space-separated list of tags in returnTag. The list of tags is consdered to be a list of synonyms, each previous owner is checked to see if its list of catchTags matches any one of the given returnTag tags.

Parameters:
returnTag - a String of tags to match a previous catchTags
Throws:
MediaBindException - a BindInProgressException if a bind or release is already in process.
See Also:
release(), releaseToService(String, int)

releaseToDestroy

public void releaseToDestroy()
                      throws MediaBindException
Release with an indication that the call is or should be disconnected and the MediaGroup destroyed.

Equivalent to releaseToTag(tag_DestroyRequest).

Throws:
MediaBindException - a BindInProgressException if a bind or release is already in process.
See Also:
releaseToTag(String)

configure

public void configure(ConfigSpec configSpec)
               throws NotBoundException,
                      MediaConfigException
Configure the bound MediaGroup according to the given configSpec.

Post-Condition: foreach R in configSpec: {(this instanceof R)} and the Resource is allocated and connected in the MediaGroup.

Note: On some implementations this method stops all media operations.

Parameters:
configSpec - a ConfigSpec describing the requested configuration
Throws:
NotBoundException - if not currently bound to a MediaGroup
MediaConfigException - if resources can not be configured as requested

getConfiguration

public ConfigSpec getConfiguration()
                            throws NotBoundException
Return a ConfigSpec that describes the current configuration of this MediaService. The returned ConfigSpec contains the attributes and parameters of the currently bound MediaGroup, including ResourceSpecs for all of the Resources currently configured into this MediaGroup.

Note:. This does not generally return a copy of the ConfigSpec used to create/configure this MediaGroup. The returned ConfigSpec describes the MediaService/MediaGroup as it is currently and actually configured.

The attributes of the individual resources appear in the ResourceSpec corresponding to that resource. The parameters and attributes of the MediaService/MediaGroup as a whole are available using ConfigSpec.getAttributes() and ConfigSpec.getParameters().

Returns:
a ConfigSpec describing the current configuration.
Throws:
NotBoundException - if not currently bound to a MediaGroup

getTerminalName

public java.lang.String getTerminalName()
                                 throws NotBoundException
Return the installation-specific String that identifies the Terminal to which this MediaService is bound.

Returns:
a String that uniquely identifies the bound Terminal.
Throws:
NotBoundException - if not currently bound to a MediaGroup
See Also:
Terminal.getName()

getTerminal

public Terminal getTerminal()
                     throws NotBoundException
Return the Terminal associated with the MediaService. The Terminal may be used to access the associated JTAPI objects.

Note: If this MediaService is not associated with a JTAPI Provider, this method may return null.

Note: This method is supplied as a potential accelerator for some implementations. Applications that need a reference to the bound Terminal without reference to other JTAPI objects should restrict their usage to getTerminalName().

Returns:
the Terminal object associated with this MediaService.
Throws:
NotBoundException - if not currently bound to a MediaGroup

stop

public void stop()
          throws NotBoundException
Stop media operations on this MediaService. Stops all ongoing media operations, unblocking any resource methods. Those operations that are stopped get a completion event with:
ResourceEvent.getQualifier() == ResourceEvent.q_Stop

This method may not unblock a bind or release request. For that effect, use cancelBindRequest().

Throws:
NotBoundException - if not currently bound to a MediaGroup

triggerRTC

public void triggerRTC(Symbol rtca)
                throws NotBoundException
Deprecated. use transactional Resource commands.

Trigger a RTC action from the application.

This is a non-blocking, one-way invocation.

This method allows the application to synthesize the triggering of RTC actions. The RTC Condition associated with this action is rtcc_TriggerRTC.

The rtca actions are documented by various Resources in the ResourceConstants interface. Look for Symbol fields with the rtca_ prefix.

Note: this method was ill-conceived and has been recalled. RTC actions internally are associated with a specific transaction. Until implementations with the correct semantics are defined, it is better to use the existing transactional commands.

For example: use Player.pause() instead of triggerRTC(Player.rtca_Pause).

In a future release there may be:
void triggerRTC(Symbol rtca, Async.Event event)
which would effect only the transaction associated with the given event.

Parameters:
rtca - a Symbol for a recognized RTC action: rtca_Action
Throws:
NotBoundException - if not currently bound to a MediaGroup

getUserValues

public java.util.Dictionary getUserValues(Symbol[] keys)
                                   throws NotBoundException
Creates and returns a new Dictionary that contains the UserDictionary values corresponding to a given set of keys.

If the keys argument is null then a snapshot of the entire UserDictionary is returned.

For interoperability with other languages, the keys in the Dictionary are restricted to type Symbol. The result of using keys of other types is undefined, but throwing a ClassCastException is considered compliant.

Parameters:
keys - an array of key Symbols
Returns:
a Dictionary of application-shared information.
Throws:
NotBoundException - if not currently bound to a MediaGroup
See Also:
setUserValues(java.util.Dictionary)

setUserValues

public void setUserValues(java.util.Dictionary dict)
                   throws NotBoundException
Set the values of several UserDictionary keys. The values supplied in the given dict are merged with the current UserDictionary.
Parameters:
dict - a Dictionary whose contents is merged into the UserDictionary.
Throws:
NotBoundException - if not currently bound to a MediaGroup
See Also:
getUserValues(javax.telephony.media.Symbol[])

setUserDictionary

public void setUserDictionary(java.util.Dictionary newDict)
                       throws NotBoundException
Set the entire UserDictionary to a new collection of key-value pairs.

Note: setUserDictionary(null) achieves the same result as setUserDictionary(new Hashtable());

Parameters:
newDict - A Dictionary whose contents is copied into the MediaGroup.
Throws:
NotBoundException - if not currently bound to a MediaGroup

getParameters

public java.util.Dictionary getParameters(Symbol[] params)
                                   throws NotBoundException
Get the value of various parameters from the MediaGroup bound to this MediaService. Each key in the returned Dictionary has the value of the corresponding parameter.

If the params is null, then get all parameters. For example:

	Dictionary parms;
	parms = getParameters(null); // on return, parms contains all parameters.
Some implementations may not be able to retrieve parameter values when one or more resources are busy. In that case, null is returned.

If a key refers to a Resource that is not present, or the resource has no meaning associated with a particular Symbol, the key is ignored, no error is generated, and that key does not appear returned Dictionary.

Parameters:
params - an array of Symbols naming parameters to be retrieved.
Returns:
a Dictionary of parameter Symbols and their values.
Throws:
NotBoundException - if not currently bound to a MediaGroup
See Also:
setParameters(java.util.Dictionary)

setParameters

public void setParameters(java.util.Dictionary params)
                   throws NotBoundException
Set the value of various parameters for the MediaGroup bound to this MediaService. For each key in the supplied Dictionary, the corresponding parameter of the MediaGroup is set to the value of that key in the Dictionary.

For interoperability with other languages, the keys in the Dictionary are restricted to type Symbol. The result of using keys of other types is undefined, but a compliant implementation may throw a ClassCastException or IllegalArgumentException.

If a parameter Symbol refers to a resource that is not present, or the MediaGroup or Resource has no meaning associated with a particular Symbol, the setting for that parameter is quietly ignored.

Parameters:
params - a Dictionary in which the keys are Symbols and the values are assigned to the parameter with that Symbol name.
Throws:
NotBoundException - if not currently bound to a MediaGroup
See Also:
getParameters(javax.telephony.media.Symbol[])

addMediaListener

public void addMediaListener(MediaListener listener)
Deprecated. As of JTAPI 1.4, replaced by addListener(EventListener)

Add a MediaListener to this MediaService.

Events generated by this MediaService are dispatched to the given listener if it implements the appropriate Listener interface.

Parameters:
listener - an object that implements one or more of the ResourceListener interfaces and/or the MediaServiceListener interface.
See Also:
removeMediaListener(javax.telephony.media.MediaListener)

removeMediaListener

public void removeMediaListener(MediaListener listener)
Deprecated. As of JTAPI 1.4, replaced by removeListener(EventListener)

Remove the MediaListener from this MediaService.
Parameters:
listener - an object that implements MediaListener
See Also:
addMediaListener(javax.telephony.media.MediaListener)

addListener

public void addListener(java.util.EventListener listener)
Add a MediaListener to this MediaService.

Events generated by this MediaService are dispatched to the given listener if it implements the appropriate Listener interface.

Note: This more general form supercedes addMediaListener(MediaListener). The EventListener is added to this MediaService, and events are delivered for any MediaListener interface implemented by the listener.

Parameters:
listener - a MediaListener for this MediaService
See Also:
removeListener(java.util.EventListener)

removeListener

public void removeListener(java.util.EventListener listener)
Remove the MediaListener from this MediaService.

Note: This more general form supercedes removeMediaListener(MediaListener).

Parameters:
listener - an object that implements MediaListener
See Also:
addListener(java.util.EventListener)

JSR-043: JTAPI-1.4

Send comments to: JSR-43@ectf.org