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.
- IDLE ---> ALERTING | CONNECTED | DISCONNECTED | FAILED | INPROGRESS
- INPROGRESS ---> ALERTING | CONNECTED | DISCONNECTED | FAILED
- ALERTING ---> CONNECTED | DISCONNECTED | FAILED | UNKNOWN
- CONNECTED ---> DISCONNECTED | FAILED | UNKNOWN
- DISCONNECTED ---> UNKNOWN
- FAILED ---> DISCONNECTED | UNKNOWN
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
-
ALERTING
- The Connection.ALERTING state implies that the Address is being notified of
an incoming call.
-
CONNECTED
- The Connection.CONNECTED state implies that a Connection and its Address is
actively part of a telephone call.
-
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.
-
FAILED
- The Connection.FAILED state indicates that a Connection to that end of the
call has failed for some reason.
-
IDLE
- The Connection.IDLE state is the initial state for all new Connections.
-
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.
-
UNKNOWN
- The Connection.UNKNOWN state implies that the implementation is unable to
determine the current state of the Connection.
-
disconnect()
- Drops a Connection from an active telephone call.
-
getAddress()
- Returns the Address object associated with this Connection.
-
getCall()
- Returns the Call object associated with this Connection.
-
getConnectionCapabilities(Terminal, Address)
- Gets the ConnectionCapabilities object with respect to a Terminal and
an Address.
-
getState()
- Returns the current state of the Connection.
-
getTerminalConnections()
- Returns an array of TerminalConnections associated with this Connection.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
- ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
The following post-conditions of this are:
- Let TerminalConnection tc[] = this.getTerminalConnections()
- tc == null or tc.length >= 1
- 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.
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:
- ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
- this.getState() == Connection.CONNECTED or Connection.ALERTING
or Connection.FAILED or Connection.INPROGRESS
- Let TerminalConnection tc[] = this.getTerminalConnections (see post-
conditions)
The post-condition predicates for this method are:
- ((this.getCall()).getProvider()).getState() == Provider.IN_SERVICE
- this.getState() == Connection.DISCONNECTED
- For all i, tc[i].getState() == TerminalConnection.DROPPED
- this.getTerminalConnections() == null.
- 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
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