JCC
v1.0

jain.application.services.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 getCall() and 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 DISCONNECTED state, it is no longer listed by the JcpCall.getConnections() method. Typically, when a JcpConnection moves into the 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.

IDLE This state is the initial state for all new Connections. Connections which are in the 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 IDLE state for long, quickly transitioning to other states.
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.
INPROGRESS This state implies that the JccConnection object has been contacted by the origination side or is contacting the destination side. The contact happens as a result of the underlying protocol messages. Under certain circumstances, the Connection may not progress beyond this state. Extension packages elaborate further on this state in various situations.
ALERTING This state implies that the Address is being notified of an incoming call.
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 CONNECTED state.
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 UNKNOWN state at any time.
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 FAILED state is because the party was busy. Connections that are in the FAILED state are still connected to the call.

Connection State Transitions

Consider the transitions given below as the ones that would be visible to the application developer in the package considered. This may be either because there is a method in that class/interface that provides that behavior (read transition) or because of events in the underlying platform. Note that we are not making any statements to the effect that the other transitions (ones not shown) are disallowed. The application developer would have to keep in mind the possibility that the "invisible" transitions can surface (become visible) in inherited classes/interfaces.

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

JcpConnection FSM

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.


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 JccConnection object has been contacted by the origination side or is 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 (bearer) connection to the party is 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. Connections that are in the FAILED state are still connected to the call.

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 JccConnection object has been contacted by the origination side or is contacting the destination side. The contact happens as a result of the underlying protocol messages. 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.

JCC
v1.0

January 19, 2001
If you have any comments or queries, please mail them to m-JAIN-JCC@notes.cc.telcordia.com

Copyright - 2001 Sun Microsystems