|
JSR-043: JTAPI-1.4 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Defines the methods for binding and controlling the media processing resources associated with a 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.
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.
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:
Method | binds 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 |
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:
Connection
to the Terminal,
or null
if there is no Connection.
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.
Connection.DISCONNECTED
state),
the method onDisconnected
is invoked for each MediaServiceListener.
The effect of disconnect on media operations is controlled by the
attribute
.
When the Connection to the Terminal is disconnected and
a_StopOnDisconnect
(a_StopOnDisconnect == TRUE)
,
then
DisconnectedException
.DisconnectedException
.
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
.
When there are no viable Connections to the Terminal
and a_DeallocateOnIdle
(a_DeallocateOnIdle == TRUE)
,
then
release
.
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.
getParameters
and setParameters
.
getConfiguration()
.getAttributes()
.
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.
MediaService is an interface; an implementation and constructor are
available from the class BasicMediaService
which
implements MediaService and various Resource interfaces.
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 |
public MediaProvider getMediaProvider()
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.
public void bindToTerminalName(ConfigSpec configSpec, java.lang.String terminalName) throws MediaBindException, MediaConfigException
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.
configSpec
- a ConfigSpec describing the requested configurationterminalName
- a String that names a media capable TerminalMediaBindException
- one of
AlreadyBoundException, BindInProgressException, BindCancelledException.MediaConfigException
- if a MediaGroup can not be configured as requestedpublic void bindToTerminal(ConfigSpec configSpec, Terminal terminal) throws MediaBindException, MediaConfigException
This is functionally equivalent to:
bindToTerminalName
(configSpec, term.getName())
,
but may perform better in some implementations.
configSpec
- a ConfigSpec describing the requested configurationterminal
- a media-capable Terminal objectMediaBindException
- one of
AlreadyBoundException, BindInProgressException, BindCancelledException.MediaConfigException
- if a MediaGroup can not be configured as requested.public void bindToServiceName(ConfigSpec configSpec, java.lang.String serviceName) throws MediaBindException, MediaConfigException
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:
serviceName
.disposition
String of
releaseToService
maps to serviceName
The mapping of disposition strings or call characteristics to service names is implementation specific, and is controlled by implementation specific administrative interfaces. For example:
releaseToService
serviceName
that matches Address.toString()
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
can be set in the ConfigSpec to override the default.
a_LocalState
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
.
configSpec
- a ConfigSpec describing the requested configurationserviceName
- the administrative name for this MediaServiceMediaBindException
- one of
AlreadyBoundException, BindInProgressException, BindCancelledException.MediaConfigException
- one of
BadConfigSpecException, ResourceNotSupportedExceptiona_LocalState
,
RunnableMediaService
public Connection bindToCall(ConfigSpec configSpec, Call call) throws MediaBindException, MediaConfigException, MediaCallException
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
.
configSpec
- a ConfigSpec describing the requested configuration.call
- a JTAPI Call objectMediaBindException
- 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.public void bindAndConnect(ConfigSpec configSpec, java.lang.String origAddr, java.lang.String dialDigits) throws MediaBindException, MediaConfigException, MediaCallException
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:
Let term =
an available media enabled Terminal at origAddr conn = call.connect(origAddr, term, dialDigits)[0];
bindToTerminal(configSpec, term)
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.
configSpec
- a ConfigSpec describing the requested configurationorigAddr
- a String identifying the origination AddressdialDigits
- a String identifying the destination AddressMediaBindException
- one of
AlreadyBoundException, BindInProgressException, BindCancelledException.MediaConfigException
- if a MediaGroup can not be configured as requested.MediaCallException
- if the Call or Connections cannot be established.Call.connect(Terminal, Address, String)
public void cancelBindRequest()
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.
public boolean isBound()
true
iff this MediaService is bound to a MediaGroup.true
iff this MediaService is bound to a MediaGroup.public void release() throws NotBoundException, MediaBindException
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)
.
NotBoundException
- if not currently bound to a MediaGroupMediaBindException
- one of:
BindInProgressException or BindCancelledException.BindInProgressException
- if a bind or release is already in progress.BindCancelledException
- if interrupted by cancelBindRequest.public void releaseToService(java.lang.String disposition, int timeout) throws NotBoundException, MediaBindException, MediaConfigException
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 |
disposition
- a String that identifies the next MediaService.timeout
- milliseconds to wait for service to become ready.NotBoundException
- if not currently bound to a MediaGroupMediaBindException
- one of:
NoServiceAssignedException, NoServiceReadyException,
BindInProgressException, BindCancelledExceptionNoServiceAssignedException
- 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.public void releaseToTag(java.lang.String returnTag) throws MediaBindException
delegateToService()
with catchTags that matche one of the given returnTags.
Some return tags have assigned usage:
Tag Name: | Used for: |
tag_NormalReturn | simple release() |
tag_DestroyRequest | releaseToDestroy |
tag_RemoveSession | releaseToRemove |
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.
returnTag
- a String of tags to match a previous catchTagsMediaBindException
- a BindInProgressException
if a bind or release is already in process.release()
,
releaseToService(String, int)
public void releaseToDestroy() throws MediaBindException
Equivalent to releaseToTag(tag_DestroyRequest).
MediaBindException
- a BindInProgressException
if a bind or release is already in process.releaseToTag(String)
public void configure(ConfigSpec configSpec) throws NotBoundException, MediaConfigException
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.
configSpec
- a ConfigSpec describing the requested configurationNotBoundException
- if not currently bound to a MediaGroupMediaConfigException
- if resources can not be configured as requestedpublic ConfigSpec getConfiguration() throws NotBoundException
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()
.
NotBoundException
- if not currently bound to a MediaGrouppublic java.lang.String getTerminalName() throws NotBoundException
NotBoundException
- if not currently bound to a MediaGroupTerminal.getName()
public Terminal getTerminal() throws NotBoundException
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()
.
NotBoundException
- if not currently bound to a MediaGrouppublic void stop() throws NotBoundException
ResourceEvent.getQualifier() == ResourceEvent.q_Stop
This method may not unblock a bind or release request.
For that effect, use cancelBindRequest()
.
NotBoundException
- if not currently bound to a MediaGrouppublic void triggerRTC(Symbol rtca) throws NotBoundException
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.
rtca
- a Symbol for a recognized RTC action: rtca_ActionNotBoundException
- if not currently bound to a MediaGrouppublic java.util.Dictionary getUserValues(Symbol[] keys) throws NotBoundException
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.
keys
- an array of key SymbolsNotBoundException
- if not currently bound to a MediaGroupsetUserValues(java.util.Dictionary)
public void setUserValues(java.util.Dictionary dict) throws NotBoundException
dict
are merged with the current UserDictionary.dict
- a Dictionary whose contents is merged into the UserDictionary.NotBoundException
- if not currently bound to a MediaGroupgetUserValues(javax.telephony.media.Symbol[])
public void setUserDictionary(java.util.Dictionary newDict) throws NotBoundException
Note:
setUserDictionary(null)
achieves the same result
as setUserDictionary(new Hashtable())
;
newDict
- A Dictionary whose contents is copied into the MediaGroup.NotBoundException
- if not currently bound to a MediaGrouppublic java.util.Dictionary getParameters(Symbol[] params) throws NotBoundException
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.
params
- an array of Symbols naming parameters to be retrieved.NotBoundException
- if not currently bound to a MediaGroupsetParameters(java.util.Dictionary)
public void setParameters(java.util.Dictionary params) throws NotBoundException
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.
params
- a Dictionary in which the keys are Symbols
and the values are assigned to the parameter with that Symbol name.NotBoundException
- if not currently bound to a MediaGroupgetParameters(javax.telephony.media.Symbol[])
public void addMediaListener(MediaListener listener)
addListener(EventListener)
Events generated by this MediaService are dispatched to the given listener if it implements the appropriate Listener interface.
listener
- an object that implements
one or more of the ResourceListener interfaces and/or
the MediaServiceListener interface.removeMediaListener(javax.telephony.media.MediaListener)
public void removeMediaListener(MediaListener listener)
removeListener(EventListener)
listener
- an object that implements MediaListeneraddMediaListener(javax.telephony.media.MediaListener)
public void addListener(java.util.EventListener listener)
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.
listener
- a MediaListener for this MediaServiceremoveListener(java.util.EventListener)
public void removeListener(java.util.EventListener listener)
Note: This more general form supercedes removeMediaListener(MediaListener).
listener
- an object that implements MediaListeneraddListener(java.util.EventListener)
|
JSR-043: JTAPI-1.4 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |