javax.telephony
Interface Connection

All Known Subinterfaces:

ACDConnection, ACDManagerConnection, CallControlConnection

public interface Connection

A Connection represents a link (i.e. an association) between a Call object and an Address object.

Introduction

The purpose of a Connection object is to describe the relationship between a Call object and an Address object. A Connection object exists if the Address is a part of the telephone call. Each Connection has a state which describes the particular stage of the relationship between the Call and Address. These states and their meanings are described below. Applications use the Connection.getCall() and Connection.getAddress() methods to obtain the Call and Address associated with this Connection, respectively.

From one perspective, an application may view a Call only in terms of the Address/Connection objects which are part of the Call. This is termed a logical view of the Call because it ignores the details provided by the Terminal and TerminalConnection objects which are also associated with a Call. In many instances, simple applications (such as an outcall program) may only need to concern itself with the logical view. In this logical view, a telephone call is views as two or more endpoint addresses in communication. The Connection object describes the state of each of these endpoint addresses with respect to the Call.

Calls and Addresses

Connection objects are immutable in terms of their Call and Address references. In other words, the Call and Address object references do not change throughout the lifetime of the Connection object instance. The same Connection object may not be used in another telephone call. The existence of a Connection implies that its Address is associated with its Call in the manner described by the Connection's state.

Although a Connection's Address and Call references remain valid throughout the lifetime of the Connection object, the same is not true for the Call and Address object's references to this Connection. Particularly, when a Connection moves into the Connection.DISCONNECTED state, it is no longer listed by the Call.getConnections() and Address.getConnections() methods. Typically, when a Connection moves into the Connection.DISCONNECTED state, the application loses its references to it to facilitate its garbage collection.

TerminalConnections

Connections objects are containers for zero or more TerminalConnection objects. Connection objects are containers for zero or more TerminalConnection objects. Connection objects represent the relationship between the Call and the Address, whereas TerminalConnection objects represent the relationship between the Connection and the Terminal. The relationship between the Call and the Address may be viewed as a logical view of the Call. The relationship between a Connection and a Terminal represents the physical view of the Call, i.e. at which Terminal the telephone calls terminates. The TerminalConnection object specification provides further information.

Connection States

Below is a description of each Connection state in real-world terms. These real-world descriptions have no bearing on the specifications of methods, they only serve to provide a more intuitive understanding of what is going on. Several methods in this specification state pre-conditions based upon the state of the Connection.

Connection.IDLE	This state is the initial state for all new Connections. Connections which are in the Connection.IDLE state are not actively part of a telephone call, yet their references to the Call and Address objects are valid. Connections typically do not stay in the Connection.IDLE state for long, quickly transitioning to other states.
Connection.DISCONNECTED	This state implies it is no longer part of the telephone call, although its references to Call and Address still remain valid. A Connection in this state is interpreted as once previously belonging to this telephone call.
Connection.INPROGRESS	This state implies that the Connection, which represents the destination end of a telephone call, is in the process of contacting the destination side. Under certain circumstances, the Connection may not progress beyond this state. Extension packages elaborate further on this state in various situations.
Connection.ALERTING	This state implies that the Address is being notified of an incoming call.
Connection.CONNECTED	This state implies that a Connection and its Address is actively part of a telephone call. In common terms, two people talking to one another are represented by two Connections in the Connection.CONNECTED state.
Connection.UNKNOWN	This state implies that the implementation is unable to determine the current state of the Connection. Typically, methods are invalid on Connections which are in this state. Connections may move in and out of the Connection.UNKNOWN state at any time.
Connection.FAILED	This state indicates that a Connection to that end of the call has failed for some reason. One reason why a Connection would be in the Connection.FAILED state is because the party was busy.

Connection State Transitions

With these loose, real-world meanings in the back of one's mind, the Connection class defines a finite-state diagram which describes the allowable Connection state transitions. This finite-state diagram must be guaranteed by the implementation. Each method which causes a change in a Connection state must be consistent with this state diagram. This finite state diagram is below:

Note there is a general left-to-right progression of the state transitions. A Connection object may transition into and out of the Connection.UNKNOWN state at any time (hence, the asterisk qualifier next to its bidirectional transition arrow).

The Connection.disconnect() Method

The primary method supported on the core package's Connection interface is the Connection.disconnect() method. This method drops an entire Connection from a telephone call. The result of this method is to move the Connection object into the Connection.DISCONNECTED state. See the specification of the Connection.disconnect() method on this page for more detailed information.

Listeners and Events

All events pertaining to the Connection object are reported via the CallListener interface on the Call object associated with this Connection. In the core package, events are reported to a CallListener when a new Connection is created and whenever a Connection 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 Connection-related events are defined in the core package. Each of these events extend the ConnectionEvent interface (which, in turn, extends the CallEvent interface).

ConnectionCreated	Indicates a new Connection has been created on a Call.
ConnectionInProgress	Indicates the Connection has moved into the Connection.INPROGRESS state.
ConnectionAlerting	Indicates the Connection has moved into the Connection.ALERTING state.
ConnectionConnected	Indicates the Connection has moved into the Connection.CONNECTED state.
ConnectionDisconnected	Indicates the Connection has moved into the Connection.DISCONNECTED state.
ConnectionFailed	Indicates the Connection has moved into the Connection.FAILED state.
ConnectionUnknown	Indicates the Connection has moved into the Connection.UNKNOWN state.

See Also:

ConnectionEvent, ConnectionListener

Field Summary

static int	ALERTING The Connection.ALERTING state implies that the Address is being notified of an incoming call.
static int	CONNECTED The Connection.CONNECTED state implies that a Connection and its Address is actively part of a telephone call.
static int	DISCONNECTED The Connection.DISCONNECTED state implies it is no longer part of the telephone call, although its references to Call and Address still remain valid.
static int	FAILED The Connection.FAILED state indicates that a Connection to that end of the call has failed for some reason.
static int	IDLE The Connection.IDLE state is the initial state for all new Connections.
static int	INPROGRESS The Connection.INPROGRESS state implies that the Connection, which represents the destination end of a telephone call, is in the process of contacting the destination side.
static int	UNKNOWN The Connection.UNKNOWN state implies that the implementation is unable to determine the current state of the Connection.

Method Summary

void	disconnect() Drops a Connection from an active telephone call.
Address	getAddress() Returns the Address object associated with this Connection.
Call	getCall() Returns the Call object associated with this Connection.
ConnectionCapabilities	getCapabilities() Returns the dynamic capabilities for the instance of the Connection object.
ConnectionCapabilities	getConnectionCapabilities(Terminal terminal, Address address) Deprecated. Since JTAPI v1.2. This method has been replaced by the Connection.getCapabilities() method.
int	getState() Returns the current state of the Connection.
TerminalConnection[]	getTerminalConnections() Returns an array of TerminalConnection objects associated with this Connection.

Field Detail

IDLE

public static final int IDLE

The Connection.IDLE state is the initial state for all new Connections. Connections which are in the Connection.IDLE state are not actively part of a telephone call, yet their references to the Call and Address objects are valid. Connections typically do not stay in the Connection.IDLE state for long, quickly transitioning to other states.

INPROGRESS

public static final int INPROGRESS

The Connection.INPROGRESS state implies that the Connection, which represents the destination end of a telephone call, is in the process of contacting the destination side. Under certain circumstances, the Connection may not progress beyond this state. Extension packages elaborate further on this state in various situations.

ALERTING

public static final int ALERTING

The Connection.ALERTING state implies that the Address is being notified of an incoming call.

CONNECTED

public static final int CONNECTED

The Connection.CONNECTED state implies that a Connection and its Address is actively part of a telephone call. In common terms, two people talking to one another are represented by two Connections in the Connection.CONNECTED state.

DISCONNECTED

public static final int DISCONNECTED

The Connection.DISCONNECTED state implies it is no longer part of the telephone call, although its references to Call and Address still remain valid. A Connection in the Connection.DISCONNECTED state is interpreted as once previously belonging to this telephone call.

FAILED

public static final int FAILED

The Connection.FAILED state indicates that a Connection to that end of the call has failed for some reason. One reason why a Connection would be in the Connection.FAILED state is because the party was busy.

UNKNOWN

public static final int UNKNOWN

The Connection.UNKNOWN state implies that the implementation is unable to determine the current state of the Connection. Typically, method are invalid on Connections which are in the Connection.UNKNOWN state. Connections may move in and out of this state at any time.

Method Detail

getState

public int getState()

Returns the current state of the Connection. The return value will be one of states defined above.

Returns:

The current state of the Connection.

getCall

public Call getCall()

Returns the Call object associated with this Connection. This Call reference remains valid throughout the lifetime of the Connection object, despite the state of the Connection object. This Call reference does not change once the Connection object has been created.

Returns:

The call object associated with this Connection.

getAddress

public Address getAddress()

Returns the Address object associated with this Connection. This Address object reference remains valid throughout the lifetime of the Connection object despite the state of the Connection object. This Address reference does not change once the Connection object has been created.

Returns:

The Address associated with this Connection.

getTerminalConnections

public TerminalConnection[] getTerminalConnections()

Returns an array of TerminalConnection objects associated with this Connection. TerminalConnection objects represent the relationship between a Connection and a specific Terminal endpoint. There may be zero TerminalConnections associated with this Connection. In that case, this method returns null. Connection objects lose their reference to a TerminalConnection once the TerminalConnection moves into the TerminalConnection.DROPPED state.

Post-conditions:

1. Let TerminalConnection tc[] = this.getTerminalConnections()
2. tc == null or tc.length >= 1
3. For all i, tc[i].getState() != TerminalConnection.DROPPED

Returns:

An array of TerminalConnection objects associated with this Connection, null if there are no TerminalConnections.

disconnect

public void disconnect()
                throws PrivilegeViolationException,
                       ResourceUnavailableException,
                       MethodNotSupportedException,
                       InvalidStateException

Drops a Connection from an active telephone call. The Connection's Address is no longer associated with the telephone call. This method does not necessarily drop the entire telephone call, only the particular Connection on the telephone call. This method provides the ability to disconnect a specific party from a telephone call, which is especially useful in telephone calls consisting of three or more parties. Invoking this method may result in the entire telephone call being dropped, which is a permitted outcome of this method. In that case, the appropriate events are delivered to the application, indicating that more than just a single Connection has been dropped from the telephone call.

Allowable Connection States

The Connection object must be in one of several states in order for this method to be successfully invoked. These allowable states are: Connection.CONNECTED, Connection.ALERTING, Connection.INPROGRESS, or Connection.FAILED. If the Connection is not in one of these allowable states when this method is invoked, this method throws InvalidStateException. Having the Connection in one of the allowable states does not guarantee a successful invocation of this method.

Method Return Conditions

This method returns successfully only after the Connection has been disconnected from the telephone call and has transitioned into the Connection.DISCONNECTED. This method may return unsuccessfully by throwing one of the exceptions listed below. Note that this method waits (i.e. the invocating thread blocks) until either the Connection is actually disconnected from the telephone call or an error is detected and an exception thrown. Also, all of the TerminalConnections associated with this Connection are moved into the TerminalConnection.DROPPED state. As a result, they are no longer reported via the Connection by the Connection.getTerminalConnections() method.

As a result of this method returning successfully, one or more events are delivered to the application. These events are listed below:

1. A ConnectionDisconnected event for this Connection.
2. A TerminalConnectionDropped event for all TerminalConnections associated with this Connection.

Dropping Additional Connections

Additional Connections may be dropped indirectly as a result of this method. For example, dropping the destination Connection of a two-party Call may result in the entire telephone call being dropped. It is up to the implementation to determine which Connections are dropped as a result of this method. Implementations should not, however, drop additional Connections if it does not reflect the natural response of the underlying telephone hardware.

Dropping additional Connections implies that their TerminalConnections are dropped as well. Also, if all of the Connections on a telephone call are dropped as a result of this method, the Call will move into the Call.INVALID state. The following lists additional events which may be delivered to the application.

1. ConnectionDisconnected/TerminalConnectionDropped are delivered for all other Connections and TerminalConnections dropped indirectly as a result of this method.
2. CallInvalid if all of the Connections are dropped indirectly as a result of this method.

Pre-conditions:

1. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Connection.CONNECTED or Connection.ALERTING or Connection.INPROGRESS or Connection.FAILED
3. Let TerminalConnection tc[] = this.getTerminalConnections (see post- conditions)

Post-conditions:

1. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Connection.DISCONNECTED
3. For all i, tc[i].getState() == TerminalConnection.DROPPED
4. this.getTerminalConnections() == null.
5. this is not an element of (this.getCall()).getConnections()
6. ConnectionDisconnected is delivered for this Connection.
7. TerminalConnectionDropped is delivered for all TerminalConnections associated with this Connection.
8. ConnectionDisconnected/TerminalConnectionDropped are delivered for all other Connections and TerminalConnections dropped indirectly as a result of this method.
9. CallInvalid if all of the Connections are dropped indirectly as a result of this method.

Throws:

PrivilegeViolationException - The application does not have the authority or permission to disconnected the Connection. For example, the Address associated with this Connection may not be controllable in the Provider's domain.

ResourceUnavailableException - An internal resource required to drop a connection is not available.

MethodNotSupportedException - This method is not supported by the implementation.

InvalidStateException - Some object required for the successful invocation of this method is not in the proper state as given by this method's pre-conditions. For example, the Provider may not be in the Provider.IN_SERVICE state or the Connection may not be in one of the allowable states.

See Also:

ConnectionListener, ConnectionEvent

getCapabilities

public ConnectionCapabilities getCapabilities()

Returns the dynamic capabilities for the instance of the Connection 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 the current state of the call model or some implementation-specific knowledge. These indications do not guarantee that a particular method can be successfully invoked, however.

The dynamic Connection capabilities require no additional arguments.

Returns:

The dynamic Connection capabilities.

getConnectionCapabilities

public ConnectionCapabilities getConnectionCapabilities(Terminal terminal,
                                                        Address address)
                                                 throws InvalidArgumentException,
                                                        PlatformException

Deprecated. Since JTAPI v1.2. This method has been replaced by the Connection.getCapabilities() method.

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

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

Parameters:

terminal - This argument is ignored in JTAPI v1.2 and later.

address - This argument is ignored in JTAPI v1.2 and later.

Returns:

The dynamic ConnectionCapabilities capabilities.

Throws:

InvalidArgumentException - This exception is never thrown in JTAPI v1.2 and later.

PlatformException - A platform-specific exception occurred.