JSR-043: JTAPI-1.4

javax.telephony
Interface TerminalConnection

All Known Subinterfaces:
CallControlTerminalConnection, MediaTerminalConnection

public interface TerminalConnection

The TerminalConnection represents the relationship between a Connection and a Terminal.

Introduction

A TerminalConnection object must always be associated with a Connection object and a Terminal object. The Connection and the Terminal objects associated with the TerminalConnection do not change throughout the lifetime of the TerminalConnection. Applications obtain the Connection and Terminal associated with the TerminalConnection via the TerminalConnection.getConnection() and TerminalConnection.getTerminal() methods, respectively.

Because a TerminalConnection is associated with a Connection, it there is also associated with some Call. The TerminalConnection describes the specific relationship between a physical Terminal endpoint with respect to an Address on a Call. TerminalConnections provide a physical view of a Call. For a particular Address endpoint on a Call, there may be zero or more Terminals at which the Call terminates. The TerminalConnection describes each specific Terminal on the Call associated with a particular Address endpoint on the Call. Many simple applications may not care about which specific Terminals are on the Call at a particular Address endpoint. In these cases, the logical view provided by Connections are sufficient.

Requirements for TerminalConnections

In order for a Terminal to be on a Call and associated with a Connection, the Terminal must be associated with the Address object endpoint of the Connection. That is, for each TerminalConnection on a Connection, the Connection's Address must be associated with the TerminalConnection's Terminal. The following predicates illustrates this necessary relationship:

  1. Let address = connection.getAddress();
  2. Let tc[] = connection.getTerminalConnections();
  3. For all i in tc[], let terminal[i] = tc[i].getTerminal();
  4. Assert for all i: address is an element of terminal[i].getAddresses();
  5. Assert for all i: terminal[i] is an element of address.getTerminals();

TerminalConnection States

The TerminalConnection has a state which describes the current relationship between a Terminal and a Connection. TerminalConnection states are distinct from Connection states. Connection states describe the relationship between an entire Address endpoint and a Call, whereas the TerminalConnection state describes the relationship between one of the Terminals at the endpoint Address on the Call with respect to its Connection. Different Terminals on a Call which are associated with the same Connection may be in different states. Furthermore, the state of the TerminalConnection has a dependency and specific relationship to the state of its Connection, as described later on.

The TerminalConnection interface in the core package has six states defined in real-world terms below:
TerminalConnection.IDLE This state is the initial state for all TerminalConnections. TerminalConnection objects do not stay in this state for long. They typically transition into another state quickly.
TerminalConnection.RINGING This state indicates the a Terminal is ringing, indicating that the Terminal has an incoming Call.
TerminalConnection.PASSIVE This state indicates that a Terminal is part of a telephone call but not in an active fashion. This may imply that a resource of the Terminal is being used and may limit actions on the Terminal.
TerminalConnection.ACTIVE This state indicates that a Terminal is actively part of a telephone call. This usually implies that the party speaking on that Terminal is part of the telephone call.
TerminalConnection.DROPPED This state indicates that a particular Terminal has permanently left the telephone call.
TerminalConnection.UNKNOWN This state indicates that the implementation is unable to determine the state of the TerminalConnection. TerminalConnections may transition into and out of this state at any time.

When a TerminalConnection moves into the TerminalConnection.DROPPED state, it is no longer associated with its Connection and Terminal. That is, both of these objects lose their references to the TerminalConnection. However, the TerminalConnection still maintains its references to the Connection and Terminal object for application reference. That is, when a TerminalConnection moves into the TerminalConnection.DROPPED state, the methods TerminalConnection.getConnection() and TerminalConnection.getTerminal() still return valid objects.

TerminalConnection state transitions

Similar to the Connection, there is a finite-state diagram which describes the allowable state transitions of a TerminalConnection. The implementation must guarantee these state transitions. The specifications of methods which affect the state of the TerminalConnections also obey these state transitions. This state diagram is below:

Note the TerminalConnection may transition into the TerminalConnection.DROPPED state from any state, and into and out of the TerminalConnection.UNKNOWN state from any state.

Relationship between Connections and TerminalConnections

As mentioned previously, the state of the Connection determines the following about TerminalConnections:

These properties about Connections and TerminalConnections are guaranteed by the implementation. This relationship is further illustrated in the description of such methods as Call.connect(), Connection.disconnected(), and TerminalConnection.answer(). The following chart defines the specific relationship between Connection states and TerminalConnections.

If the Connection is in state... ... then the TerminalConnection is
Connection.IDLE No TerminalConnections may exist on this Connection, that is, the Connection.getTerminalConnections() method returns null.
Connection.INPROGRESS No TerminalConnections may exist on this Connection, that is, the Connection.getTerminalConnections() method returns null.
Connection.ALERTING Zero or more TerminalConnections may exist on this Connection, and each must be in the TerminalConnection.RINGING state.
Connection.CONNECTED Zero or more TerminalConnections may exist on this Connection, and each must be in the TerminalConnection.PASSIVE or the TerminalConnection.ACTIVE state. Note that when TerminalConnections must into the TerminalConnection.DROPPED state they are no longer associated with the Connection.
Connection.DISCONNECTED No TerminalConnections may exist on this Connection, that is, the Connection.getTerminalConnections() method returns null. Note that all TerminalConnections previously associated with this Connection will move into the TerminalConnection.DROPPED state.
Connection.FAILED No TerminalConnections may exist on this Connection, that is, the Connection.getTerminalConnections() method returns null. Note that all TerminalConnections previously associated with this Connection will move into the TerminalConnection.DROPPED state.
Connection.UNKNOWN Zero or more TerminalConnections may exist on this Connection, and each must be in the TerminalConnection.UNKNOWN state.

The TerminalConnection.answer() Method

The primary method supported on the core package's TerminalConnection interface is the TerminalConnection.answer() method. This method answers a telephone call at a Terminal. This method moves the TerminalConnection into the TerminalConnection.ACTIVE state upon success. The TerminalConnection must be in the TerminalConnection.RINGING state when this method is invoked.

Listeners and Events

All events pertaining to the TerminalConnection object are reported via the CallListener interface on the Call object associated with this TerminalConnection. In the core package, events are reported to a CallListener when a new TerminalConnection is created and whenever a TerminalConnection changes state. Listeners are added to Call objects via the Call.addCallListener() method and more indirectly via the Address.addCallListener() and Terminal.addCallListener() methods. See the specifications for the Call, Address, and Terminal interfaces for more information.

The following TerminalConnection-related events are defined in the core package. Each of these events extend the TerminalConnectionEvent interface (which, in turn, extends the CallEvent interface).

TerminalConnectionCreated Indicates a new TerminalConnection has been created on a Connection.
TerminalConnectionRinging Indicates the TerminalConnection has moved into the TerminalConnection.RINGING state.
TerminalConnectionActive Indicates the TerminalConnection has moved into the TerminalConnection.ACTIVE state.
TerminalConnectionPassive Indicates the TerminalConnection has moved into the TerminalConnection.PASSIVE state.
TerminalConnectionDropped Indicates the TerminalConnection has moved into the TerminalConnection.DROPPED state.
TerminalConnectionUnknown Indicates the TerminalConnection has moved into the TerminalConnection.UNKNOWN state.

See Also:
CallListener, TerminalConnectionListener, TerminalListener, TerminalConnectionEvent, CallEvent

Field Summary
static int ACTIVE
          This state indicates that a Terminal is actively part of a telephone call.
static int DROPPED
          This state indicates that a particular Terminal has permanently left the telephone call.
static int IDLE
          This state is the initial state for all TerminalConnection objects.
static int PASSIVE
          This state indicates that a Terminal is part of a telephone call but not in an active fashion.
static int RINGING
          This state indicates the a Terminal is ringing, indicating that the Terminal has an incoming Call.
static int UNKNOWN
          This state indicates that the implementation is unable to determine the state of the TerminalConnection.
 
Method Summary
 void answer()
          Answers an incoming telephone call on this TerminalConnection.
 TerminalConnectionCapabilities getCapabilities()
          Returns the dynamic capabilities for the instance of the TerminalConnection object.
 Connection getConnection()
          Returns the Connection object associated with this TerminalConnection.
 int getState()
          Returns the state of the TerminalConnection object.
 Terminal getTerminal()
          Returns the Terminal associated with this TerminalConnection object.
 TerminalConnectionCapabilities getTerminalConnectionCapabilities(Terminal terminal, Address address)
          Deprecated. Since JTAPI v1.2. This method has been replaced by the TerminalConnection.getCapabilities() method.
 

Field Detail

IDLE

public static final int IDLE
This state is the initial state for all TerminalConnection objects.

RINGING

public static final int RINGING
This state indicates the a Terminal is ringing, indicating that the Terminal has an incoming Call.

PASSIVE

public static final int PASSIVE
This state indicates that a Terminal is part of a telephone call but not in an active fashion. This may imply that a resource of the Terminal is being used and may limit actions on the Terminal.

ACTIVE

public static final int ACTIVE
This state indicates that a Terminal is actively part of a telephone call. This usually implies that the party speaking on that Terminal is party of the telephone call.

DROPPED

public static final int DROPPED
This state indicates that a particular Terminal has permanently left the telephone call.

UNKNOWN

public static final int UNKNOWN
This state indicates that the implementation is unable to determine the state of the TerminalConnection.
Method Detail

getState

public int getState()
Returns the state of the TerminalConnection object.

Returns:
The current state of the TerminalConnection object.

getTerminal

public Terminal getTerminal()
Returns the Terminal associated with this TerminalConnection object. A TerminalConnection's reference to its Terminal remains valid for the lifetime of the object, even if the Terminal loses its references to this TerminalConnection object. Also, this reference does not change once the TerminalConnection object has been created.

Returns:
The Terminal object associated with this TerminalConnection.

getConnection

public Connection getConnection()
Returns the Connection object associated with this TerminalConnection. A TerminalConnection's reference to the Connection remains valid throughout the lifetime of the TerminalConnection. Also, this reference does not change once the TerminalConnection object has been created.

Returns:
The Connections associated with this TerminalConnection.

answer

public void answer()
            throws PrivilegeViolationException,
                   ResourceUnavailableException,
                   MethodNotSupportedException,
                   InvalidStateException
Answers an incoming telephone call on this TerminalConnection. This method waits (i.e. the invoking thread blocks) until the telephone call has been answered at the endpoint before returning. When this method returns successfully, the state of this TerminalConnection object is TerminalConnection.ACTIVE.

Allowable TerminalConnection States

The TerminalConnection must be in the TerminalConnection.RINGING state when this method is invoked. According to the specification of the TerminalConnection object, this state implies the associated Connection object is also in the Connection.ALERTING state. There may be more than one TerminalConnection on the Connection which are in the TerminalConnection.RINGING state. In fact, if the Connection is in the Connection.ALERTING state, all of these TerminalConnections must be in the TerminalConnection.RINGING state. Any of these TerminalConnections may invoke this method to answer the telephone call.

Multiple TerminalConnections

The underlying telephone hardware determines the resulting state of other TerminalConnection objects after the telephone call has been answered by one of the TerminalConnections. The other TerminalConnection object may either move into the TerminalConnection.PASSIVE state or the TerminalConnection.DROPPED state. If a TerminalConnection moves into the TerminalConnection.PASSIVE state, it remains part of the telephone call, but not actively so. It may have the ability to join the call in the future. If a TerminalConnection moves into the TerminalConnection.DROPPED state, it is removed from the telephone call and will never have the ability to join the call in the future. The appropriate events are delivered to the application indicates into which of these two states the other TerminalConnection objects have moved.

Events

The following events are reported to applications via the CallListener interface as a result of the successful outcome of this method:

  1. TerminalConnectionActive for the TerminalConnection which invoked this method.
  2. ConnectionConnected for the Connection associated with the TerminalConnection.
  3. TerminalConnectionPassive or TerminalConnectionActive for other TerminalConnections associated with the Connection.

Pre-conditions:

  1. ((this.getTerminal()).getProvider()).getState() == Provider.IN_SERVICE
  2. this.getState() == TerminalConnection.RINGING
  3. (this.getConnection()).getState() == Connection.ALERTING
Post-conditions:
  1. ((this.getTerminal()).getProvider()).getState() == Provider.IN_SERVICE
  2. this.getState() == TerminalConnection.ACTIVE
  3. (this.getConnection()).getState() == Connection.CONNECTED
  4. TerminalConnectionActive for the TerminalConnection which invoked this method.
  5. ConnectionConnected for the Connection associated with the TerminalConnection.
  6. TerminalConnectionPassive or TerminalConnectionActive for other TerminalConnections associated with the Connection.
Throws:
PrivilegeViolationException - The application did not have proper authority to answer the telephone call. For example, the Terminal associated with the TerminalConnection may not be in the Provider's local domain.
ResourceUnavailableException - The necessary resources to answer the telephone call were not available when the method was invoked.
MethodNotSupportedException - This method is currently not supported by this implementation.
InvalidStateException - An object was not in the proper state, violating the pre-conditions of this method. For example, the Provider was not in the Provider.IN_SERVICE state or the TerminalConnection was not in the TerminalConnection.RINGING state.
See Also:
TerminalConnectionListener, ConnectionListener, TerminalConnectionEvent, ConnectionEvent

getCapabilities

public TerminalConnectionCapabilities getCapabilities()
Returns the dynamic capabilities for the instance of the TerminalConnection object. Dynamic capabilities tell the application which actions are possible at the time this method is invoked based upon the implementations knowledge of its ability to successfully perform the action. This determination may be based upon argument passed to this method, the current state of the call model, or some implementation- specific knowledge. These indications do not guarantee that a particular method will be successful when invoked, however.

The dynamic TerminalConnection capabilities require no additional arguments.

Returns:
The dynamic TerminalConnection capabilities.

getTerminalConnectionCapabilities

public TerminalConnectionCapabilities getTerminalConnectionCapabilities(Terminal terminal,
                                                                        Address address)
                                                                 throws InvalidArgumentException,
                                                                        PlatformException
Deprecated. Since JTAPI v1.2. This method has been replaced by the TerminalConnection.getCapabilities() method.

Gets the TerminalConnectionCapabilities object with respect to a Terminal and an Address. If null is passed as a Terminal parameter, the general/ provider-wide Terminal Connection capabilities are returned.

Note: This method has been replaced in JTAPI v1.2. The TerminalConnection.getCapabilities() method returns the dynamic TerminalConnection capabilities. This method now should simply invoke the TerminalConnection.getCapabilities() method.

Parameters:
address - This argument is ignored in JTAPI v1.2 and later.
terminal - This argument is ignored in JTAPI v1.2 and later.
Returns:
The static TerminalConnectionCapabilities capabilities.
Throws:
InvalidArgumentException - This exception is never thrown in JTAPI v1.2 and later.
PlatformException - A platform-specific exception occurred.

JSR-043: JTAPI-1.4

Send comments to: JSR-43@ectf.org