JSR-043: JTAPI-1.4

Package javax.telephony.media.connection

Defines the MediaConnection interface which is used to control the connection of media streams between MediaService objects.

See:
          Description

Interface Summary
Cnx Allow short names for constants.
Connectable A marker interface identifying objects that can be used as arguments to MediaConnection.connect() and related methods.
MediaConnection The MediaService API for inter-Group connections.
MediaConnection.Token Each Token represents a connection between the the MediaGroups of two bound MediaService objects.
MediaConnectionConstants Symbol constants used by MediaConnection.
MediaConnectionEvent Completion Event from connect() and related methods.
MediaConnectionListener For non-Transactional connection events.
 

Exception Summary
MediaConnectionException The class of things that go wrong in MediaConnection methods.
 

Package javax.telephony.media.connection Description

Defines the MediaConnection interface which is used to control the connection of media streams between MediaService objects.

Package Overview

This package defines a intra-group media connection interface for S.410 (javax.telephony.media) MediaServices.

Media Connections are used to connect media streams between the MediaGroups of two MediaServices. The connections are modeled as bi-directional streams, but the data flow can be restricted to mute flow in either or both directions.

System Model for Media Connections

This diagram shows two MediaGroups (A and B). Every MediaGroup has a Primary Stream (marked A1 and B1), and one or more Secondary Streams (marked A2 and B2).

A Media Group has a Primary Stream,
that connects internally to the configured Resources
Figure 1

Data coming in to the MediaGroup on the Primary Stream can be heard by all Resources in the MediaGroup. Data generated by any Resource in the MediaGroup is sent out on the Primary Stream. Secondary Streams are treated like Resources: Secondary Streams listen to the Primary Stream, and output from a Secondary Stream is sent out the Primary Stream.

The Primary Stream is connected internally to the various processing Resources in a MediaGroup (a Player and Recorder are shown) by the MediaService.configure() method.

The Primary Stream is (typcially) connected externally to a telephony/network device; which JTAPI calls a Terminal. Terminals that can be connected as the Primary Stream of a MediaGroup are marked as implementing MediaTerminal

Note, that from the point of view of the telephony network, the Media Group is inside a Terminal. The Player and Recorder are like the tape player and recorder in your home answering machine; when your answering machine plays your greeting, the internal tape player is connected to the telephony Terminal and plays out to the network.

Arbitration

Note that if more that one Resource or Secondary stream is talking to the Primary Stream, a decision must be made about how to mix the competing sources. That decision is part of the magic configuration logic in the Media Group. The decision of how to handle multiple talkers is called the arbitration scheme for the Media Group.

The most common arbitration scheme is called the Last Talker Algorithm or "LTA" for short. The LTA says simply: that source that started talking "last" (that is, most recently) is the source that is transmitted out the Primary Stream. If/when that source stops talking, the Primary Stream resumes transmitting the previous talker. Internally, a stack is maintained; if a source stops it is removed from the stack, if a source starts it is pushed on the top of the stack. LTA is useful because predicatable effects can be implemented without additional DSP resources.

An alternative arbitration scheme is to mix the two or more competing talkers (similar to the operation of a conference bridge).

Media Connection methods

The MediaConnection package allows the application to control the external connections between MediaGroups. Given two MediaGroups (A and B, in the diagram above), there are three ways they can be connected:
Topology:Terminology: Connection typeSymbol
A2 connected to B2 A and B bridged SecondaryToSecondaryv_Bridge
A1 connected to B1 loopback between A and B PrimaryToPrimaryv_Loopback
A1 connected to B2 A joins B PrimaryToSecondaryv_Join

The connect() method creates any of the three types of connections as determined by the connectionType argument.

Methods bridge(), join(), loopback() are wrappers around connect() that use the indicated connection type.

The setDataFlow() method selectively enables or disables data flow in either direction for the stream.

When MediaGroup is bridged to MediaGroup B, the party connected to A1 (via the telephony network) will hear the Player in A and/or the party connected to B1. The party at A1 can be heard by the Recorder in A and by the party at B1. The Recorder in B cannot hear A1, and the Player in B cannot be heard by A1.

When MediaGroup and MediaGroup B are connected by a loopback, then there is no external network connection. The Player in A can be heard by the Recorder in B.

When MediaGroup A joins MediaGroup B, the effect is as if the Resouces of A become Resources of B. That is, the Resources of A listen to the Primary Stream of B, and compete to talk to the Primary Stream of B.

Shows a Primary-to-Primary Bridge Shows a Secondary-to-Secondary Loopback Shows a Primary-to-Secondary Bridge
Figure 2

Note:The streaming connections for bridged or loopback topologies are symetrical. A.bridge(B) has the same result as B.bridge(A) and A.loopback(B) has the same result as B.loopback(A). Of course, the sense of DataFlow is reversed: v_Talk and v_Listen refer to the object of the method, not to the argument.

Note: if a MediaGroup has a Primary Stream connected to an external network (that is, to a MediaTerminal), then it is not possible to connect that Primary Stream to a MediaGroup using loopback() or join(). The initial ConfigSpec of the MediaService when it is bound determines if the Primary Stream is connected to a MediaTerminal or is available for the MediaConnection methods.

Synchronous and Asychronous APIs

The interface javax.telephony.media.connection.MediaConnection defines the basic synchronous methods: The Event and Listener and Async interfaces are derived from MediaConnection following the same patterns used for MediaService methods.

The API Symbol constants for the MediaConnection package are defined, by convention, in MediaConnectionConstants; which name is rather lengthy. So the interface Cnx is supplied to provide a shorter form. For example, one can use Cnx.v_Join instead of MediaConnectionConstants.v_Join.

Since:
JTAPI-1.4

JSR-043: JTAPI-1.4

Send comments to: JSR-43@ectf.org