|
JSR-043: JTAPI-1.4 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
A Connection
represents a link (i.e. an association) between
a Call
object and an Address
object.
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.
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.
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.
|
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).
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.
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.
|
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 |
public static final int IDLE
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.public static final int INPROGRESS
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.public static final int ALERTING
Connection.ALERTING
state implies that the Address is
being notified of an incoming call.public static final int CONNECTED
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.public static final int DISCONNECTED
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.public static final int FAILED
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.public static final int UNKNOWN
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 |
public int getState()
public Call getCall()
public Address getAddress()
public TerminalConnection[] getTerminalConnections()
TerminalConnection.DROPPED
state.
Post-conditions:
public void disconnect() throws PrivilegeViolationException, ResourceUnavailableException, MethodNotSupportedException, InvalidStateException
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.
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:
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.
Pre-conditions:
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.ConnectionListener
,
ConnectionEvent
public ConnectionCapabilities getCapabilities()
The dynamic Connection capabilities require no additional arguments.
public ConnectionCapabilities getConnectionCapabilities(Terminal terminal, Address address) throws InvalidArgumentException, PlatformException
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.
terminal
- This argument is ignored in JTAPI v1.2 and later.address
- This argument is ignored in JTAPI v1.2 and later.InvalidArgumentException
- This exception is never thrown in
JTAPI v1.2 and later.PlatformException
- A platform-specific exception occurred.
|
JSR-043: JTAPI-1.4 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |