jain.jcp
Interface JcpCall

All Known Subinterfaces:
JccCall

public interface JcpCall

A JcpCall is a transient association of (zero or more) addresses for the purposes of engaging in a real-time communications interchange. The call and its associated connection and address objects describe the control and media flows taking place in some underlying "real world" communication network. Other parties involved in the call may also exert control over it, thus the membership and state of the endpoints may change without explicit request by the jcp application. The JcpProvider adjusts the call, address and connection objects to reflect the results of these combined command actions.

Introduction

A JcpCall can have zero or more JcpConnections. A two-party call has two JcpConnections, and a conference call has three or more JcpConnections. Each JcpConnection models the relationship between a JcpCall and an JcpAddress, where an JcpAddress identifies a particular party or set of parties on a call.

Creating JcpCall Objects

Applications create instances of a JcpCall object with the JcpProvider.createCall() method, which returns a JcpCall object that has zero Connections and is in the IDLE state. The JcpCall maintains a reference to its JcpProvider for the life of that JcpCall object. The JcpProvider object instance does not change throughout the lifetime of the JcpCall object. The JcpProvider associated with a JcpCall is obtained via the getProvider() method.

JcpCall States

A JcpCall has a state which is obtained via the getState() method. This state describes the current progress of a telephone call, where is it in its life cycle, and how many connections exist on the call. The JcpCall state may be one of three values: IDLE, ACTIVE, or INVALID. The following is a description of each state:
JcpCall.IDLE This is the initial state for all calls. In this state, the JcpCall has zero connections, that is getConnections() must return null.
JcpCall.ACTIVE A call with some current ongoing activity is in this state. JcpCalls with one or more associated JcpConnections must be in this state. If a JcpCall is in this state, the getConnections() method must return an array of size at least one.
JcpCall.INVALID This is the final state for all calls. JcpCall objects which lose all of their JcpConnection objects (via a transition of the JcpConnection object into the JcpConnection.DISCONNECTED state) moves into this state. Calls in this state have zero JcpConnections and these JcpCall objects may not be used for any future action. In this state, the getConnections() must return null.

JcpCall State Transitions

The possible Call state transitions are given in the diagram below:

JcpCall and JcpConnection objects

A JcpCall maintains a list of the JcpConnections on that JcpCall. Applications obtain an array of JcpConnections associated with the JcpCall via the getConnections() method. A JcpCall retains a reference to a JcpConnection only if it is not in the JcpConnection.DISCONNECTED state. Therefore, if a JcpCall has a reference to a JcpConnection, then that JcpConnection must not be in the JcpConnection.DISCONNECTED state. When a JcpConnection moves into the JcpConnection.DISCONNECTED state (e.g. when a party hangs up), the JcpCall loses its reference to that JcpConnection which is no longer reported via the JcpCall.getConnections() method.

Listeners and Events

The JcpCallListener interface reports all events pertaining to the JcpCall object. Events delivered to this interface must extend the JcpCallEvent interface. Applications can add listeners to a JcpCall object via the addCallListener(JcpCallListener) method.

Connection-related events can be reported via the JcpCallListener interface or via the JcpConnectionListener interface. These events include the creation of these objects and their state changes. Events which are reported via the JcpCallListener interface pertaining to JcpConnections extend the JcpConnectionEvent interface.

Event Snapshots
By default, when an listener is added to a telephone call, the first batch of events may be a "snapshot". That is, if the listener was added after state changes in the Call, the first batch of events will inform the application of the current state of the Call. Note that these snapshot events do NOT provide a history of all events on the Call, rather they provide the minimum necessary information to bring the application up-to-date with the current state of the Call.
When Event Transmission Ends
At times it may become impossible for the implementation to report events to an application. In this case, a JcpCallEvent.CALL_EVENT_TRANSMISSION_ENDED is delivered to an object registered as a JcpCallListener (or an extension of that interface).

This is the final event receives by the Listener.

Registering JcpCallListeners via Provider
Applications may receive events about a JcpCall by adding a Listener via the JcpCall or JcpProvider objects using the addCallListener() methods.

See Also:
JcpCallListener, JcpConnectionListener, JcpConnection, JcpAddress, JcpCallEvent

Field Summary
static int ACTIVE
          JcpCall.ACTIVE state indicates the Call has one or more Connections none of which is in the JcpConnection.DISCONNECTED state.
static int IDLE
          JcpCall.IDLE state indicates the Call has zero Connections.
static int INVALID
          The JcpCall.INVALID state indicates that the Call has lost all of its connections, that is, all of its Connection objects have moved into the JcpConnection.DISCONNECTED state and are no longer associated with the Call.
 
Method Summary
 void addCallListener(JcpCallListener calllistener)
          Add a listener to this call.
 JcpConnection[] getConnections()
          Retrieves an array of connections asssociated with this call.
 JcpProvider getProvider()
          Retrieves the provider handling this call object.
 int getState()
          Retrieves the state of the call.
 void removeCallListener(JcpCallListener calllistener)
          Removes a listener from this call.
 

Field Detail

IDLE

public static final int IDLE
JcpCall.IDLE state indicates the Call has zero Connections. This is the initial state of all Call objects.

ACTIVE

public static final int ACTIVE
JcpCall.ACTIVE state indicates the Call has one or more Connections none of which is in the JcpConnection.DISCONNECTED state. The Call object transitions into this state from the IDLE state only.

INVALID

public static final int INVALID
The JcpCall.INVALID state indicates that the Call has lost all of its connections, that is, all of its Connection objects have moved into the JcpConnection.DISCONNECTED state and are no longer associated with the Call. A Call in this state cannot be used for future actions.
Method Detail

getState

public int getState()
Retrieves the state of the call. The state will be either IDLE, ACTIVE or INVALID.
Returns:
Integer representing the state of the call.

addCallListener

public void addCallListener(JcpCallListener calllistener)
                     throws ResourceUnavailableException,
                            MethodNotSupportedException
Add a listener to this call. This also reports all state changes in the state of the Call and Connection objects. The listener added with this method will report events on the call for as long as the implementation can listen to the Call. In the case that 1.the implementation can no longer observe the Call
2.this listener has been removed from this Call
3. the Call has completed and moved to the JcpCall.INVALID state the application receives a CALL_EVENT_TRANSMISSION_ENDED event.

CallListeners from Provider
There may be additional call listeners on the call which were not added by this method. These listeners may have become part of the call via the JcpProvider.addCallListener() method. See the specifications for these methods for more information.
Multiple Invocations
If an application attempts to add an instance of an listener already present on this Call, there are two possible outcomes:

  1. If the listener was added by the application using this method, then a repeated invocation will silently fail, i.e. multiple instances of an listener are not added and no exception will be thrown.
  2. If the listener is part of the call because an application invoked JccProvider.addCallListener() either of these methods modifies the behavior of that listener as if it were added via this method instead.

Post-Conditions:

  1. A snapshot of events is delivered to the listener, if appropriate.

Parameters:
calllistener - JcpCallListener object that receives the specified events.
Throws:
MethodNotSupportedException - The listener cannot be added at this time.
ResourceUnavailableException - The resource limit for the number of listeners has been exceeded.

removeCallListener

public void removeCallListener(JcpCallListener calllistener)
Removes a listener from this call. If successful, the listener will receive a CALL_EVENT_TRANSMISSION_ENDED as the last event it receives. If the listener is not part of the Call for the given address(es), then this method fails silently, i.e. no listener is removed and no exception is thrown.

This method has different effects depending upon how the listener was added to the Call, as follows:

  1. If the listener was added via JcpCall.addCallListener(), this method removes the listener until it is re-applied by the application.
  2. If the listener was added via JccProvider.addCallListener(), this method removes the listener for this call only. It does not affect whether this listener will be added to future calls which come to that Address. See JccProvider.addCallListener() for more details.

If an listener is not part of the Call, then this method fails silently, i.e. no listener is removed and no exception is thrown.

Post-Conditions:

  1. CALL_EVENT_TRANSMISSION_ENDED is delivered to the application

Parameters:
calllistener - JcpCall Listener object.

getProvider

public JcpProvider getProvider()
Retrieves the provider handling this call object. The Provider reference does not change once the Call object has been created, despite the state of the Call object.

Returns:
JcpProvider object managing this call.

getConnections

public JcpConnection[] getConnections()
Retrieves an array of connections asssociated with this call. None of the Connections returned will be in the JcpConnection.DISCONNECTED state. Further, if the Call is in the IDLE or INVALID state, this method returns null.

Post-Conditions:
    1. JcpConnection[] conn=JcpCall.getConnections()
    2. if this.getState() == JcpCall.IDLE then conn=null
    3.if this.getState == JcpCall.INVALID then conn=null
    4. if this.getState == JcpCall.ACTIVE then conn.length >=1
    5. For all i, conn[i].getState() != JcpConnection.DISCONNECTED

    Returns:
    Array of Connections for this call.


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


Copyright-2000 Sun Microsystems