jain.jcp
Interface JcpConnection

All Known Subinterfaces:
JccConnection

public interface JcpConnection

Introduction

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

From one perspective, an application may view a JcpCall only in terms of the JcpAddress/JcpConnection objects which are part of the JcpCall. This is termed a logical view of the Call. In this logical view, a telephone call is viewed as two or more endpoint addresses in communication. The JcpConnection object describes the state of each of these endpoint addresses with respect to the JcpCall.

JcpCalls and JcpAddresses

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

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

Connection States

Below is a description of each JcpConnection 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.

JcpConnection.IDLE This state is the initial state for all new Connections. Connections which are in the JcpConnection.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 JcpConnection.IDLE state for long, quickly transitioning to other states.
JcpConnection.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.
JcpConnection.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.
JcpConnection.ALERTING This state implies that the Address is being notified of an incoming call.
JcpConnection.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 JcpConnection.CONNECTED state.
JcpConnection.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 JcpConnection.UNKNOWN state at any time.
JcpConnection.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 JcpConnection.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 JcpConnection class defines a finite-state diagram which describes the allowable JcpConnection state transitions. This finite-state diagram must be guaranteed by the implementation. Each method which causes a change in a JcpConnection 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 JcpConnection object may transition into and out of the JcpConnection.UNKNOWN state at any time (hence, the asterisk qualifier next to its bidirectional transition arrow).

Listeners and Events

All events pertaining to the JcpConnection object are reported via the JcpCallListener interface on the JcpCall object associated with this JcpConnection. Events are reported to a JcpCallListener when a new JcpConnection is created and whenever a JcpConnection changes state. Listeners are added to JcpCall objects via the JccCall.addCallListener() method and more indirectly via the JccProvider.addCallListener() method. See the specifications for the JccCall and JccProvider interfaces for more information.


Field Summary
static int ALERTING
          The JcpConnection.ALERTING state implies that the Address is being notified of an incoming call.
static int CONNECTED
          The JcpConnection.CONNECTED state implies that originating and terminating connection objects and the associated Address objects are actively part of a call.
static int DISCONNECTED
          The JcpConnection.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 JcpConnection.FAILED state indicates that a Connection to that end of the call has failed for some reason.
static int IDLE
          The JcpConnection.IDLE state is the initial state for all new JcpConnection objects.
static int INPROGRESS
          The JcpConnection.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 JcpConnection.UNKNOWN state implies that the implementation is unable to determine the current state of the Connection.
 
Method Summary
 JcpAddress getAddress()
          Returns the JcpAddress associated with this JcpConnection.
 JcpCall getCall()
          Retrieves the Jcpcall that is associated with this Jcpconnection.
 int getState()
          Retrieves the state of the JcpConnection object.
 

Field Detail

DISCONNECTED

public static final int DISCONNECTED
The JcpConnection.DISCONNECTED state implies it is no longer part of the telephone call, although its references to Call and Address still remain valid. Entry criteria: This state is entered when a disconnect indication is received from the corresponding party or the application. Function: The connections for the originating and terminating party are disconnected and depending on the incoming network connection, appropriate backward signaling takes place. Exit criteria:

IDLE

public static final int IDLE
The JcpConnection.IDLE state is the initial state for all new JcpConnection objects. A JcpConnection object in the IDLE state while not yet actively participating in a call can still reference a JcpCall and JcpAddress object.
Entry criteria Start of a new call.
Functions: Interface (line/trunk) is idled.
Exit criteria: An indication of the desire to place an outgoing call or when the indication of an incoming call is received.

ALERTING

public static final int ALERTING
The JcpConnection.ALERTING state implies that the Address is being notified of an incoming call.
Entry criteria: This state is entered when the terminating party is being alerted of an incoming call. Function: An indication is sent to the originating party that the terminating party is being alerted. Exit criteria: This state is exited when the call is accepted and answered by the terminating party. Exception criteria such as callrejected, NoAnswer and Abandon if possible all cause exit from this state.

CONNECTED

public static final int CONNECTED
The JcpConnection.CONNECTED state implies that originating and terminating connection objects and the associated Address objects are actively part of a call. Entry criteria: This state is entered when the Call is accepted and answered by the terminating party. Function: In this state several processes related to message accounting/charging, call supervision etc. may be initiated if such a capability is provided by the implementation. Exit criteria: Exception criteria such as disconnect (and suspend for JCC) cause exit from this state.

FAILED

public static final int FAILED
The JcpConnection.FAILED state indicates that a Connection to that end of the call has failed for some reason. One reason why a JcpConnection would be in the FAILED state is due to the fact that the party was busy. Entry criteria: This state is entered when an exception condition is encountered. Function: Default handling of the exception condition is provided. Exit criteria: Default handling of the exception condition by the implementation is completed.

UNKNOWN

public static final int UNKNOWN
The JcpConnection.UNKNOWN state implies that the implementation is unable to determine the current state of the Connection. This indicates that the platform does not know of the current state of the corresponding JccConnection object.

INPROGRESS

public static final int INPROGRESS
The JcpConnection.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.
Method Detail

getState

public int getState()
Retrieves the state of the JcpConnection object.

Returns:
Integer representing the state of the call. See static int's defined in this object.

getCall

public JcpCall getCall()
Retrieves the Jcpcall that is associated with this Jcpconnection. This JcpCall reference remains valid throughout the lifetime of the JcpConnection object despite the state of the JcpConnection object. This JcpCall reference does not change once the JcpConnection object has been created.

Returns:
JcpCall object holding this connection.

getAddress

public JcpAddress getAddress()
Returns the JcpAddress associated with this JcpConnection. This JcpAddress object remains valid throughout the lifetime of the JcpConnection object despite the state of the JcpConnection object. This JcpAddress reference does not change once the JcpConnection object has been created.

Returns:
JcpAddress object associated with this JcpConnection object.


3 Oct 2000
If you have any comments or queries, please mail them to jcc@research.telcordia.com


Copyright-2000 Sun Microsystems