javax.telephony
Interface Call

All Known Subinterfaces:

CallCenterCall, CallControlCall

public interface Call

A Call object models a telephone call.

Introduction

A Call can have zero or more Connections. A two-party call has two Connections, and a conference call has three or more Connections. Each Connection models the relationship between a Call and an Address, where an Address identifies a particular party or set of parties on a Call.

Creating Call Objects

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

Call States

A Call has a state which is obtained via the Call.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 Call state may be one of three values: Call.IDLE, Call.ACTIVE, or Call.INVALID. The following is a description of each state:

Call.IDLE	This is the initial state for all Calls. In this state, the Call has zero Connections, that is Call.getConnections() must return null.
Call.ACTIVE	A Call with some current ongoing activity is in this state. Calls with one or more associated Connections must be in this state. If a Call is in this state, the Call.getConnections() method must return an array of size at least one.
Call.INVALID	This is the final state for all Calls. Call objects which lose all of their Connections objects (via a transition of the Connection object into the Connection.DISCONNECTED state) moves into this state. Calls in this state have zero Connections and these Call objects may not be used for any future action. In this state, the Call.getConnections() must return null.

Call State Transitions

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

Calls and Connections

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

The Call.connect() method

The primary method on this interface is the Call.connect() method. Applications use this method to place a telephone call from an originating endpoint to a destination address string. The result of this method on the call model is to create an originating and destination Connection and move the Call into the Call.ACTIVE state. As the new telephone call progresses during its lifetime, the state of various objects associated with the Call may change and new objects may be created and associated with the Call. See the specification of the Call.connect() method below for more details.

Listeners and Observers

In JTAPI 1.2 and earlier versions, the way a JTAPI application arranged to receive events about telephony activity was to register an application object as an Observer of one or more JTAPI objects.

Starting with JTAPI 1.3, the primary way to arrange for a provider to report events is to use Listeners, following the pattern established in Java release 1.1 (see Event for more details). The Observer model is supported but its use is deprecated with this release.

Listeners and Events

The CallListener interface reports all events pertaining to the Call object. Events delivered to this interface must extend the CallEvent interface. Applications add listeners to a Call object via the Call.addCallListener() method.

Connection-related and TerminalConnection-related events are also reported via the CallListener interface. These events include the creation of these objects and their state changes. Events which are reported via the CallListener interface pertaining to Connections and TerminalConnections extend the ConnectionEvent interface and the TerminalConnectionEvent interface, respectively.

An event is delivered to the application whenever the state of the Call changes. The event interfaces corresponding to Call state changes are: CallActiveEventID and CallInvalidEventID.

When Call Event Transmission Ends

At times it may become impossible for the implementation to report events to an application. In this case, a CALL_EVENT_TRANSMISSION_ENDED is delivered to an object registered as a CallListener (or an extension of that interface).

This is the final event receives by the Listener, and it is no longer reported via the Call.getCallListeners() method.

Event Granularity

An application may control the granularity of events which are reported. Registering for the highest level interface (CallListener) will direct the implementation to send only Call-related events (including MetaEvents). To register as a Listener at a lower level interfaces (ConnectionListener or TerminalConnectionListener) directs the implementation to provide successively more detailed events.

Registering Call Listeners via Address and Terminal

Applications may receive events about a Call by adding an Listener via the Address or Terminal objects using the Address.addCallListener() and Terminal.addCallListener() (and related) methods. These methods provide the ability for an application to receive Call-related events when a Call contains a particular Address or Terminal. In particular, methods exist to add a CallListener, ConnectionListener and TerminalConnectionListener via Address and Terminal. See the specifications for Address and Terminal for more details.

See Also:

CallListener, ConnectionListener, TerminalConnectionListener, Connection, Address, Terminal, TerminalConnection, CallEvent

Field Summary

static int	ACTIVE The Call.ACTIVE state indicates the Call has one or more Connections, none of which are in the Connection.DISCONNECTED state.
static int	IDLE The Call.IDLE state indicates the Call has zero Connections.
static int	INVALID The Call.INVALID state indicates the Call has lost all of its connections - that is, all of its associated Connection objects have moved into the Connection.DISCONNECTED state and are no longer associated with the Call.

Method Summary

void	addCallListener(CallListener listener) Adds an listener to the Call.
void	addObserver(CallObserver observer) Adds an observer to the Call.
Connection[]	connect(Terminal origterm, Address origaddr, java.lang.String dialedDigits) Places a telephone call from an originating endpoint to a destination address string.
CallCapabilities	getCallCapabilities(Terminal term, Address addr) Deprecated. Since JTAPI v1.2. This method has been replaced by the Call.getCapabilities() method.
CallListener[]	getCallListeners() Returns an array of all CallListeners on this Call.
CallCapabilities	getCapabilities(Terminal terminal, Address address) Returns the dynamic capabilities for the instance of the Call object.
Connection[]	getConnections() Returns an array of Connections associated with this call.
CallObserver[]	getObservers() Returns an array of all CallObservers on this Call.
Provider	getProvider() Returns the Provider associated with the Call.
int	getState() Returns the current state of the telephone call.
void	removeCallListener(CallListener listener) Removes the given listener from the Call.
void	removeObserver(CallObserver observer) Removes the given observer from the Call.

Field Detail

IDLE

public static final int IDLE

The Call.IDLE state indicates the Call has zero Connections. It is the initial state of all Call objects.

ACTIVE

public static final int ACTIVE

The Call.ACTIVE state indicates the Call has one or more Connections, none of which are in the Connection.DISCONNECTED state.

INVALID

public static final int INVALID

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

Method Detail

getConnections

public Connection[] getConnections()

Returns an array of Connections associated with this call. Note that none of the Connections returned will be in the Connection.DISCONNECTED state. Also, if the Call is in the Call.IDLE state or the Call.INVALID state, this method returns null. Otherwise, it returns one or more Connection objects.

Post-conditions:

1. Let Connection[] conn = Call.getConnections()
2. if this.getState() == Call.IDLE then conn = null
3. if this.getState() == Call.INVALID then conn = null
4. if this.getState() == Call.ACTIVE then conn.length >= 1
5. For all i, conn[i].getState() != Connection.DISCONNECTED

Returns:

An array of the Connections associated with the call.

getProvider

public Provider getProvider()

Returns the Provider associated with the Call. This Provider reference remains valid throughout the lifetime of the Call object, despite the state of the Call object. This Provider reference does not change once the Call object has been created.

Returns:

The Provider associated with the call.

getState

public int getState()

Returns the current state of the telephone call. The state will be either Call.IDLE, Call.ACTIVE, or Call.INVALID.

Returns:

The current state of the call.

connect

public Connection[] connect(Terminal origterm,
                            Address origaddr,
                            java.lang.String dialedDigits)
                     throws ResourceUnavailableException,
                            PrivilegeViolationException,
                            InvalidPartyException,
                            InvalidArgumentException,
                            InvalidStateException,
                            MethodNotSupportedException

Places a telephone call from an originating endpoint to a destination address string.

The Call must be in the Call.IDLE state (and therefore have no existing associated Connections and the Provider must be in the Provider.IN_SERVICE state. The successful effect of this method is to place the telephone call and create and return two Connections associated with this Call.

Method Arguments

This method has three arguments. The first argument is the originating Terminal for the telephone call. The second argument is the originating Address for the telephone Call. This Terminal/Address pair must reference one another. That is, the originating Address must appear on the Terminal (via Address.getTerminals() and the originating Terminal must appear on the Address (via Terminal.getAddress()). If not, an InvalidArgumentException is thrown.

The third argument is a destination string whose value represents the address to which the telephone call is placed. This destination address must be valid and complete.

Method Post-conditions

This method returns successfully when the Provider can successfully initiate the placing of the telephone call. As a result, when the Call.connect() method returns, the Call will be in the Call.ACTIVE state and exactly two Connections will be created and returned. The Connection associated with the originating endpoint is the first Connection in the returned array, and the Connection associated with the destination endpoint is the second Connection in the returned array. These two Connections must at least be in the Connection.IDLE state. That is, if one of the Connections progresses beyond the Connection.IDLE state while this method is completing, this Connection may be in a state other than the Connection.IDLE. This state must be reflected by an event sent to the application.

Call Scenarios or Flows

As a telephone call progresses during its lifetime, the various objects associated with the Call may change state and new objects may be created an associated with the Call. These changes typically occur after this method has successfully returned.

How the Call and its associated objects progress depends upon real-world conditions. There is a large but finite number of ways in which the state of a Call may progress. It is difficult to enumerate each possible way in which the state of a Call may progress. Instead, several illustrative scenarios (also called flows) are presented for common real-world conditions. These scenarios obey the valid state transitions as defined by the Call, Connection, and TerminalConnection objects.

Two common scenarios are presented below. Note that there may exist additional scenarios very similar to these which may only differ in a single step or state change. Any implementation which adheres to the rules outlined by the Call, Connection, and TerminalConnection objects is considered a proper implementations with respect to call flows.

Normal Call.connect() Scenario

This this scenario, a telephone call is placed to a telephone number address. This address is outside the Provider's domain. The destination party answers the telephone call.

1. The Call.connect() method is invoked with the given arguments. Two Connection objects are created and returned, each in the Connection.IDLE state.

   Events delivered to the application: a CallActivEv and two ConnectionCreatedEventID, one for each Connection.

2. Once the Provider begins to place the telephone call, the originating Connection moves from the Connection.IDLE state into the Connection.CONNECTED state. A TerminalConnection is created in the TerminalConnection.IDLE state and moves into the to model the TerminalConnection.ACTIVE relationship between the originating Terminal and the Connection.

   Events delivered to the application: a ConnectionEvent.CONNECTION_CONNECTED for the originating Connection, a TerminalConnectionEvent.TERMINAL_CONNECTION_CREATED and a TerminalConnection.TERMINAL_CONNECTION_ACTIVE for the new TerminalConnection.

   Note: Depending upon the configuration of the switch, additional TerminalConnection objects associated with the originating Connection may be created. If the originating Address has more than on Terminal, these additional Terminals may be involved in the telephone call. For each TerminalConnection created a TerminalConnectionEvent.TERMINAL_CONNECTION_CREATED is delivered. Typically, these TerminalConnections will be in the TerminalConnection.PASSIVE state and a TerminalConnectionEvent.TERMINAL_CONNECTION_PASSIVE is delivered for each.

3. The destination Connection into the Connection.INPROGRESS state as the Call proceeds.

   Events delivered to the application: a ConnectionEvent.CONNECTION_IN_PROGRESS for the destination Connection.

4. The destination Connection moves into the Connection.ALERTING state as the destination is alerted to the telephone call. TerminalConnection object may be created to model the relationship between any known destination Terminals associated with the Call, each in the TerminalConnection.RINGING state. If the destination Terminals are unknown, then no TerminalConnections are created.

   Events delivered to the application: a ConnectionEvent.CONNECTION_ALERTING for the destination Connection, a TerminalConnectionEvent.TERMINAL_CONNECTION_CREATED and TerminalConnectionEvent.TERMINAL_CONNECTION_RINGING for any destination TerminalConnections created.

5. The destination Connection moves into the Connection.CONNECTED state when the called party answers the telephone call. If the destination Terminals are known, the answering TerminalConnection moves into the TerminalConnection.ACTIVE state.

   Events delivered to the application: a ConnectionEvent.CONNECTION_CONNECTED for the destination Connection and a TerminalConnectionEvent.TERMINAL_CONNECTION_ACTIVE for the answering TerminalConnection, if known.

   Note: For all other non-answering destination TerminalConnections known, either one of two state changes will occur depending upon the configuration of the switch. These TerminalConnections will either move into the TerminalConnection.PASSIVE state or the TerminalConnection.DROPPED state, depending upon whether or not these Terminals continue as part of the telephone call. For each, either a TerminalConnectionEvent.TERMINAL_CONNECTION_PASSIVE or TerminalConnectionEvent.TERMINAL_CONNECTION_DROPPED is delivered.

At the conclusion of this scenario, the Call will be in the Call.ACTIVE state, both Connections will be in the Connection.CONNECTED state, and the originating TerminalConnection will be in the TerminalConnection.ACTIVE state.

Failure Call.connect() Scenario

In this scenario, a telephone call is placed to a destination address. The destination cannot be reached, perhaps because the destination address is busy.

The first three steps of the first scenario are the same as in this scenario. They are not repeated here for brevity. The fourth and final step of this scenario is:

1. The destination Connection moves into the Connection.FAILED because the destination party could not be reached. (e.g. busy)

   Events delivered to the application: a ConnectionEvent.CONNECTION_FAILED is delivered for the destination Connection.

At the conclusion of this scenario, the Call will be in the Call.ACTIVE state, the originating Connection will be in the Connection.CONNECTED state, the destination Connection will be in the Connection.FAILED state, and the originating TerminalConnection will be in the TerminalConnection.ACTIVE state.

Pre-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.IDLE

Post-conditions:

1. (this.getProvider()).getState() == Provider.IN_SERVICE
2. this.getState() == Call.ACTIVE
3. Let Connection c[] = this.getConnections()
4. c.length == 2
5. c[0].getState() == Connection.IDLE (at least)
6. c[1].getState() == Connection.IDLE (at least)

Parameters:

origterm - The originating Terminal for this telephone call.

origaddr - The originating Address for this telephone call.

dialedDigits - The destination address string for this telephone call.

Returns:

array of Connections

Throws:

ResourceUnavailableException - An internal resource necessary for placing the phone call is unavailable.

PrivilegeViolationException - The application does not have the proper authority to place a telephone call.

InvalidPartyException - Either the originator or the destination does not represent a valid party required to place a telephone call.

InvalidArgumentException - An argument provided is not valid either by not providing enough information for this method or is inconsistent with another argument.

InvalidStateException - Some object required by this method is not in a valid state as designated by the pre-conditions for this method.

MethodNotSupportedException - The implementation does not support this method.

See Also:

CallEvent, ConnectionEvent, TerminalConnectionEvent

addObserver

public void addObserver(CallObserver observer)
                 throws ResourceUnavailableException,
                        MethodNotSupportedException

Adds an observer to the Call. The CallObserver reports all Call-related events. This includes changes in the state of the Call and all Connection-related and TerminalConnection-related events. The observer added with this method will report events on the call for as long as the implementation can observer the Call. In the case that the implementation can no longer observe the Call, the applications receives a CallObservationEndedEv. The observer receives no more events after it receives the CallObservationEndedEv and is no longer reported via the Call.getObservers() method.

Observer Lifetime

The CallObserver will receive events until one of the following occurs, whereupon the observer receives a CallObservationEndedEv and the observer is no longer reported via the Call.getObservers() method.

1. The observer is removed by the application with Call.removeObserver().
2. The implementation can no longer monitor the call.
3. The Call has completed and moved into the Call.INVALID state.

Event Snapshots

By default, when an observer is added to a telephone call, the first batch of events may be a "snapshot". That is, if the observer 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. The meta code for all of these events will be Ev.META_SNAPSHOT.

CallObservers from Addresses and Terminals

There may be additional call observers on the call which were not added by this method. These observers may have become part of the call via the Address.addCallObserver() and Terminal.addCallObserver() methods. See the specifications for these methods for more information.

Multiple Invocations

If an application attempts to add an instance of an observer already present on this Call, there are two possible outcomes:

1. If the observer was added by the application using this method, then a repeated invocation will silently fail, i.e. multiple instances of an observer are not added and no exception will be thrown.
2. If the observer is part of the call because an application invoked Address.addCallObserver() or Terminal.addCallObserver(), either of these methods modifies the behavior of that observer as if it were added via this method instead. That is, the observer is no longer removed when the call leaves the Address or Terminal. The observer now receives events until one of the conditions in "Observer Lifetime" is met.

Post-Conditions:

1. observer is an element of this.getObservers()
2. A snapshot of events is delivered to the observer, if appropriate.

Parameters:

observer - The observer being added.

Throws:

MethodNotSupportedException - The observer cannot be added at this time

ResourceUnavailableException - The resource limit for the numbers of observers has been exceeded.

getObservers

public CallObserver[] getObservers()

Returns an array of all CallObservers on this Call. If no observers are on this Call object, then this method returns null. This method returns all observers on this call no matter how they were added to the Call. Call observers may be added to this call in one of three ways:

1. The application added the observer via Call.addObserver().
2. The application added the observer via Address.addCallObserver() and the call came to that Address.
3. The application added the observer via Terminal.addCallObserver() and the call came to that Terminal.

An instance of a CallObserver object will only appear once in this list.

Post-Conditions:

1. Let CallObserver[] obs = this.getObservers()
2. obs == null or obs.length >= 1

Returns:

An array of CallObserver objects associated with this Call.

removeObserver

public void removeObserver(CallObserver observer)

Removes the given observer from the Call. If successful, the observer will receive a CallObservationEndedEv as the last event it receives and will no longer be reported via the Call.getObservers() method.

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

1. If the observer was added via Call.addObserver(), this method removes the observer until it is re-applied by the application.
2. If the observer was added via Address.addCallObserver() or Terminal.addCallObserver(), this method removes the observer for this call only. It does not affect whether this observer will be added to future calls which come to that Address. See Address.addCallObserver() and Terminal.addCallObserver() for more details.

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

Post-Conditions:

1. observer is not an element of this.getObservers()
2. CallObservationEndedEv is delivered to the application

Parameters:

observer - The observer which is being removed.

getCapabilities

public CallCapabilities getCapabilities(Terminal terminal,
                                        Address address)
                                 throws InvalidArgumentException

Returns the dynamic capabilities for the instance of the Call object. Dynamic capabilities tell the application which actions are possible at the time this method is invoked based upon the implementations knowledge of its ability to successfully perform the action. This determination may be based upon argument passed to this method, the current state of the call model, or some implementation-specific knowledge. These indications do not guarantee that a particular method can be successfully invoked, however.

The dynamic call capabilities are based upon a Terminal/Address pair as well as the instance of the Call object. These parameters are used to determine whether certain call actions are possible at the present. For example, the CallCapabilities.canConnect() method will indicate whether a telephone call can be placed using the Terminal/Address pair as the originating endpoint.

Parameters:

terminal - Dynamic capabilities are with respect to this Terminal.

address - Dynamic capabilities are with respect to this Address.

Returns:

The dynamic Call capabilities.

Throws:

InvalidArgumentException - Indicates the Terminal and/or Address argument provided was not valid.

getCallCapabilities

public CallCapabilities getCallCapabilities(Terminal term,
                                            Address addr)
                                     throws InvalidArgumentException,
                                            PlatformException

Deprecated. Since JTAPI v1.2. This method has been replaced by the Call.getCapabilities() method.

Gets the CallCapabilities object with respect to a Terminal and an Address. If null is passed as a Terminal parameter, the general/provider-wide Call capabilities are returned.

Note: This method has been replaced in JTAPI v1.2. The Call.getCapabilities() method returns the dynamic Call capabilities. This method now should simply invoke the Call.getCapabilities() method with the given Terminal and Address arguments.

Parameters:

term - Dynamic Call capabilities in JTAPI v1.2 are with respect to this Terminal.

addr - Dynamic Call capabilities in JTAPI v1.2 are with respect to this Address.

Returns:

dynamic call capabilities

Throws:

InvalidArgumentException - Indicates the Terminal and/or Address argument provided was not valid.

PlatformException - A platform-specific exception occurred.

addCallListener

public void addCallListener(CallListener listener)
                     throws ResourceUnavailableException,
                            MethodNotSupportedException

Adds an listener to the Call. The CallListener reports all Call-related events. This includes changes in the state of the Call and all Connection-related and TerminalConnection-related events. The listener added with this method will report events on the call for as long as the implementation can listener the Call. In the case that the implementation can no longer observe the Call, the applications receives a CALL_EVENT_TRANSMISSION_ENDED. The listener receives no more events after it receives the CALL_EVENT_TRANSMISSION_ENDED and is no longer reported via the Call.getCallListeners() method.

Listener Lifetime

The CallListener will receive events until one of the following occurs, whereupon the listener receives a CALL_EVENT_TRANSMISSION_ENDED and the listener is no longer reported via the Call.getCallListeners() method.

1. The listener is removed by the application with Call.removeCallListener().
2. The implementation can no longer monitor the call.
3. The Call has completed and moved into the Call.INVALID state.

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. The meta code for all of these events will be Event.META_SNAPSHOT.

CallListeners from Addresses and Terminals

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 Address.addCallListener() and Terminal.addCallListener() (or related) methods. 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 Address.addCallListener() or Terminal.addCallListener(), either of these methods modifies the behavior of that listener as if it were added via this method instead. That is, the listener is no longer removed when the call leaves the Address or Terminal. The listener now receives events until one of the conditions in "Listener Lifetime" is met.

Post-Conditions:

1. listener is an element of this.getCallListeners()
2. A snapshot of events is delivered to the listener, if appropriate.

Parameters:

listener - The listener being added.

Throws:

MethodNotSupportedException - The listener cannot be added at this time

ResourceUnavailableException - The resource limit for the numbers of listeners has been exceeded.

getCallListeners

public CallListener[] getCallListeners()

Returns an array of all CallListeners on this Call. If no listeners are on this Call object, then this method returns null. This method returns all listeners on this call no matter how they were added to the Call. Call listeners may be added to this call in one of three ways:

1. The application added the listener via Call.addCallListener().
2. The application added the listener via Address.addCallListener() and the call came to that Address.
3. The application added the listener via Terminal.addCallListener() and the call came to that Terminal.

An instance of a CallListener object will only appear once in this list.

Post-Conditions:

1. Let CallListener[] obs = this.getCallListeners()
2. obs == null or obs.length >= 1

Returns:

An array of CallListener objects associated with this Call.

removeCallListener

public void removeCallListener(CallListener listener)

Removes the given listener from the Call. If successful, the listener will receive a CALL_EVENT_TRANSMISSION_ENDED as the last event it receives and will no longer be reported via the Call.getCallListeners() method.

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

1. If the listener was added via Call.addCallListener(), this method removes the listener until it is re-applied by the application.
2. If the listener was added via Address.addCallListener() or Terminal.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 Address.addCallListener() and Terminal.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. listener is not an element of this.getCallListeners()
2. CALL_EVENT_TRANSMISSION_ENDED is delivered to the application

Parameters:

listener - The listener which is being removed.