Interface java.telephony.Connection
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface java.telephony.Connection

public interface Connection
extends Object
A Connection represents a link (i.e. an association) between a Call object and an Address object. The purpose of a Connection object is to describe this relationship between the Address and a Call. 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. For example, when the Address is actively part of a telephone call, the Connection state which relates the two is CONNECTED. If there is an incoming call to an Address, the Connection state is ALERTING. These various states are described below. In most situations, the state of the Connection describes what actions are possible on the Connection.

Connection objects are immutable in terms of its 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 faciliate its garbage collection.

Connections may be viewed as a container 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 Call and the Terminal. The relationship between the Call and the Address may be views as a "logical" view of the Call, i.e. where the endpoints are telephone number addresses. The relationship between a Call 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.

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.

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.

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.

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.

The Connection.ALERTING state implies that the Address is being notified of an incoming call. Typically, the Connection.ALERTING Connection will answer the telephone call.

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.

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 the Connection.UNKNOWN state at any time.

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.

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. The finite state diagram of the Connection states appears in graphical in the Overview document for the Java Telephony API. Below, the finite state diagram appears below in text:

All states may transition into and out of the UNKNOWN state which is not represented below.

The Connection object supports the disconnect() method which drops an entire Connection from the telephone call. The result of this method is to move this Connection object into the Connection.DISCONNECTED state at which time the address, nor any of its Terminals are associated with the telephone call.

When a Connection object changes state, the application is notified via an event through the CallObserver interface. A Call object is notified only if the Connection is part of the Call. The CallObserver interface is also notified when a new Connection has been created on a Call.

See Also:
CallObserver

Variable Index

 o ALERTING
The Connection.ALERTING state implies that the Address is being notified of an incoming call.
 o CONNECTED
The Connection.CONNECTED state implies that a Connection and its Address is actively part of a telephone call.
 o 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.
 o FAILED
The Connection.FAILED state indicates that a Connection to that end of the call has failed for some reason.
 o IDLE
The Connection.IDLE state is the initial state for all new Connections.
 o 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.
 o UNKNOWN
The Connection.UNKNOWN state implies that the implementation is unable to determine the current state of the Connection.

Method Index

 o disconnect()
Drops a Connection from an active telephone call.
 o getAddress()
Returns the Address object associated with this Connection.
 o getCall()
Returns the Call object associated with this Connection.
 o getConnectionCapabilities(Terminal, Address)
Gets the ConnectionCapabilities object with respect to a Terminal and an Address.
 o getState()
Returns the current state of the Connection.
 o getTerminalConnections()
Returns an array of TerminalConnections associated with this Connection.

Variables

 o IDLE
  public final static 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.
 o INPROGRESS
  public final 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. Under certain circumstances, the Connection may not progress beyon this state. Extension packages elaborate further on this state in various situations.
 o ALERTING
  public final static int ALERTING
The Connection.ALERTING state implies that the Address is being notified of an incoming call. Typically, the Connection.ALERTING Connection will answer the telephone call.
 o CONNECTED
  public final static 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.
 o DISCONNECTED
  public final 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. A Connection in the Connection.DISCONNECTED state is interpreted as once previously belonging to this telephone call.
 o FAILED
  public final static 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.
 o UNKNOWN
  public final static 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 the Connection.UNKNOWN state at any time.

Methods

 o getState
  public abstract int getState() throws PlatformException
Returns the current state of the Connection. The return value will be one of states defined above.

Returns:
The current state of the Connection.
Throws: PlatformException
An platform-specific exception occurred.
 o getCall
  public abstract Call getCall() throws PlatformException
Returns the Call object associated with this Connection. This Call reference remains valid throughout the lifetime of the Connection object, despite its current state. This Call reference does not change after this object is created.

Returns:
The call object associated with this Connection.
Throws: PlatformException
A platform-specific exception occurred.
 o getAddress
  public abstract Address getAddress() throws PlatformException
Returns the Address object associated with this Connection. This Address object reference remains valid throughout the lifetime of the Connection object despite its current state. This Address reference does not change after this object is created.

Returns:
The Address associated with this Connection.
Throws: PlatformException
A platform-specific exception occurred.
 o getTerminalConnections
  public abstract TerminalConnection[] getTerminalConnections() throws InvalidStateException, PlatformException
Returns an array of TerminalConnections associated with this Connection. TerminalConnection objects represent the relationship between a Call 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. The Provider must be in the Provider.IN_SERVICE state for this method to be valid.

The pre-conditions for this method are:

  1. ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE

The following post-conditions of this are:

  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
Throws: InvalidStateException
The Provider is not IN_SERVICE.
Throws: PlatformException
A platform-specific exception occurred.
 o disconnect
  public abstract void disconnect() throws PrivilegeViolationException, ResourceUnavailableException, MethodNotSupportedException, InvalidStateException, PlatformException
Drops a Connection from an active telephone call. The Connection's Address is no longer associated with the telephone call. The Connection object must either be in the Connection.CONNECTED, the Connection.ALERTING, the Connection.INPROGRESS, or the Connection.FAILED states in order for this method to succeed, although this pre-condition does not guarantee its success. This method returns upon success when this Connection moves to the Connection.DISCONNECTED state. Also, all of the TerminalConnections associated with this Connection move to the TerminalConnection.DROPPED state. These TerminalConnections are no longer reported by this Connection.

The pre-condition predicates for this method are:

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

The post-condition predicates for this method are:

  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()

When this method returns, the following events are reported on the CallObserver interface for the Call associated with this Connection: a java.telephony.events.ConnDisconnectedEv for this Connection, and a java.telephony.events.TermConnDroppedEv for all of its Terminal Connections.

Throws: PrivilegeViolationException
The application does not have the authority to drop the Connection.
Throws: ResourceUnavailableException
An internal resource required to drop a connection is not available.
Throws: MethodNotSupportedException
This method is not supported by the implementation.
Throws: 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.
Throws: PlatformException
A platform-specific exception occurred.
See Also:
ConnDisconnectedEv, TermConnDroppedEv

 o getConnectionCapabilities
  public abstract ConnectionCapabilities getConnectionCapabilities(Terminal terminal,
                                                                   Address address) throws InvalidArgumentException, PlatformException
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.

Throws: PlatformException
A platform-specific exception occurred.

All Packages  Class Hierarchy  This Package  Previous  Next  Index