javax.telephony
Interface CallListener

All Superinterfaces:

java.util.EventListener

All Known Subinterfaces:

CallCenterCallListener, CallControlCallListener, CallControlConnectionListener, CallControlTerminalConnectionListener, ConnectionListener, PrivateDataCallListener, TerminalConnectionListener

public interface CallListener

extends java.util.EventListener

The CallListener interface reports all changes to the Call object.

Introduction

Call Events and Call MetaEvents

JTAPI generally provides a common model and standard interface to telephony applications, to enable the application to portably represent and control calls. Again generally there is a telephony platform on the other side of the API, which internally represents the objects and operations differently - often at a different level of granularity.

Since some individual changes to a call as represented by the telephony platform result in many changes in state in the corresponding JTAPI objects, the telephony platform's JTAPI implementation needs a way to mark a group of JTAPI events, calling them related, all originating from a single change in the telephony platform and its calls.

Applications may care because they may draw incorrect conclusions about the state of Calls after having processed only a fraction of a set of events generated in response to a single provider change of state.

In JTAPI 1.2, in order to indicate that a collection of JTAPI events all were in response to a single common telephony platform event, the convention was to deliver JTAPI events in batches. JTAPI 1.2 events delivered in a single batch were produced in response to a single telephony platform change of state.

JTAPI 1.3 introduces the Java 1.2 Event Model pattern of Event Listeners, which expect to receive events one at a time; hence batches are no longer used. Since the related events do not arrive as a group, JTAPI 1.3 provides new events, called MetaEvents, which show when such a group begins and ends.

In addition to helping the application know how the events are grouped, MetaEvents also convey information about larger granularity events. Some specifically carry information about call merging and transferring (see MultiCallMetaEvent).

Registering as a Listener

Therefore the CallListener interface conveys JTAPI Events and MetaEvents which indicate changes to the Call and related Calls. Applications which need to know about changes to a Call, may register as a listener to that Call; in order to do so the listener must implement this (CallListener) interface.

In order to register as a listener for events reported for all calls involving a specific Address, as soon as the Calls are created, an application may implement the CallListener interface and then register with the Address, via the Address.addCallListener method.

Connection Event and TerminalConnection Event listeners

The above discussion describes how an application may arrange to be notified of Call related state changes. An application may be notified, in addition, of Connection and TerminalConnection events, by registering as a listener for extensions of this interface - that is, as a ConnectionListener or as a TerminalConnectionListener.

In addition to the CallEvents and MetaEvents described above, listeners to these interfaces receive Connection events (ConnectionListener) or Connection and TerminalConnection events (TerminalConnectionListener).

These other interfaces extend the CallListener interface, to guarantee a Listener a synchronous stream of Meta, Call, Connection and TerminalConnection events in the expected order. To have a seperate Connection Listener might leave an application open to race conditions, where events coming on seperate listener threads could come in an unexpected order.

The cost to an application which cares only about Connection or TerminalConnection events is small, in that relatively few other events are reported on those interfaces; in addition, the programming burden is mitigated by convenient adapters ( naturally we need to provide adapters here! like CallListenerAdapter).

State changes are reported as events to the Listener method corresponding to the type of event.

Adding a Listener to a Call

Applications must instantiate an object which implements the appropriate listener interface and then register the Call Listener using one of several mechanisms described below to receive all future events associated with the Call and (as requested) its Connections and TerminalConnections. Applications may add a listener to a Call via one of several mechanisms. They may directly add a listener via the Call.addCallListener method. Applications may also add listeners to Calls indirectly via the Address.addCallListener and Terminal.addCallListener methods. These methods add the given listener to the Call when the Call comes to the Address or Terminal. See the specifications for Call, Address, and Terminal for more information.

Call State Changes

In the core package, an event is delivered whenever the Call changes state. The methods which are called with an event to indicate when these state changes occur, are: Call.callActiveEvent and Call.callInvalidEvent.

Meta Events

Meta events (MetaEvent) pertaining to this Call are reported on this interface. In the core package, a meta event is delivered to this interface to provide higher-level context for a sequence of JTAPI "regular" events. The Meta events indicate appropriate times for an application to query the JTAPI model, and convey details about higher-level activities and operations (see MetaEvent for more information).

Call Listener Ending

At various times, the underlying implementation may not be able to provide events noting Call state changes. In these instances, the CallListener is sent an event via the callEventTransmissionEnded method. This indicates that the application will not receive further events associated with the Call object. This listener is no longer reported via the Call.getCallListeners method.

See Also:

Call, CallEvent, ConnectionEvent, TerminalConnectionEvent, MetaEvent, MultiCallMetaEvent, SingleCallMetaEvent

Method Summary

void	callActive(CallEvent event) The callActive method is called to indicate that the state of the Call object has changed to Call.ACTIVE.
void	callEventTransmissionEnded(CallEvent event) The callEventTransmissionEnded method is called to indicate that the the application will no longer receive CallEvent events on the instance of the CallListener.
void	callInvalid(CallEvent event) The callInvalid method is called to indicate that the state of the Call object has changed to Call.INVALID.
void	multiCallMetaMergeEnded(MetaEvent event) This method indicates that a merge operation has ended, and that no further related events will be reported.
void	multiCallMetaMergeStarted(MetaEvent event) This method indicates that a merge operation is starting, and that related events will now be reported.
void	multiCallMetaTransferEnded(MetaEvent event) This method indicates that a merge operation has ended, and that no further related events will be reported.
void	multiCallMetaTransferStarted(MetaEvent event) This method indicates that a transfer operation is starting, and that related events will now be reported.
void	singleCallMetaProgressEnded(MetaEvent event) This method indicates that all events reported to convey the state change have been reported.
void	singleCallMetaProgressStarted(MetaEvent event) This method indicates that a state change has occurred for this Call entity, and that related events will now be reported.
void	singleCallMetaSnapshotEnded(MetaEvent event) This method indicates that the last event necessary to reconstruct the current state of this call has been reported.
void	singleCallMetaSnapshotStarted(MetaEvent event) This method indicates that JTAPI events will be reported to help the application reconstruct the current state of this call.

Method Detail

callActive

public void callActive(CallEvent event)

The callActive method is called to indicate that the state of the Call object has changed to Call.ACTIVE.

Parameters:

event - A CallEvent with eventID "Call.CALL_ACTIVE".

callInvalid

public void callInvalid(CallEvent event)

The callInvalid method is called to indicate that the state of the Call object has changed to Call.INVALID.

Parameters:

event - A CallEvent with eventID "Call.CALL_INVALID".

callEventTransmissionEnded

public void callEventTransmissionEnded(CallEvent event)

The callEventTransmissionEnded method is called to indicate that the the application will no longer receive CallEvent events on the instance of the CallListener.

Parameters:

event - A CallEvent with eventID "Call.CALL_EVENT_TRANSMISSION_ENDED".

singleCallMetaProgressStarted

public void singleCallMetaProgressStarted(MetaEvent event)

This method indicates that a state change has occurred for this Call entity, and that related events will now be reported. See SingleCallMetaEvent.SINGLECALL_META_PROGRESS_STARTED for details.

Parameters:

event - A MetaEvent with eventID "SingleCallMetaEvent.SINGLECALL_META_PROGRESS_STARTED".

singleCallMetaProgressEnded

public void singleCallMetaProgressEnded(MetaEvent event)

This method indicates that all events reported to convey the state change have been reported. See SingleCallMetaEvent.SINGLECALL_META_PROGRESS_ENDED for details.

Parameters:

event - A MetaEvent with eventID "SingleCallMetaEvent.SINGLECALL_META_PROGRESS_ENDED".

singleCallMetaSnapshotStarted

public void singleCallMetaSnapshotStarted(MetaEvent event)

This method indicates that JTAPI events will be reported to help the application reconstruct the current state of this call. See SingleCallMetaEvent.SINGLECALL_META_SNAPSHOT_STARTED for details.

Parameters:

event - A MetaEvent with eventID "SingleCallMetaEvent.SINGLECALL_META_SNAPSHOT_STARTED".

singleCallMetaSnapshotEnded

public void singleCallMetaSnapshotEnded(MetaEvent event)

This method indicates that the last event necessary to reconstruct the current state of this call has been reported. See SingleCallMetaEvent.SINGLECALL_META_SNAPSHOT_ENDED for details.

Parameters:

event - A MetaEvent with eventID "SingleCallMetaEvent.SINGLECALL_META_SNAPSHOT_ENDED".

multiCallMetaMergeStarted

public void multiCallMetaMergeStarted(MetaEvent event)

This method indicates that a merge operation is starting, and that related events will now be reported. See MultiCallMetaEvent.MULTICALL_META_MERGE_STARTED for details.

Parameters:

event - A MetaEvent with eventID "MultiCallMetaEvent.MULTICALL_META_MERGE_STARTED".

multiCallMetaMergeEnded

public void multiCallMetaMergeEnded(MetaEvent event)

This method indicates that a merge operation has ended, and that no further related events will be reported. See MultiCallMetaEvent.MULTICALL_META_MERGE_ENDED for details.

Parameters:

event - A MetaEvent with eventID "MultiCallMetaEvent.MULTICALL_META_MERGE_ENDED".

multiCallMetaTransferStarted

public void multiCallMetaTransferStarted(MetaEvent event)

This method indicates that a transfer operation is starting, and that related events will now be reported. See MultiCallMetaEvent.MULTICALL_META_TRANSFER_STARTED for details.

Parameters:

event - A MetaEvent with eventID "MultiCallMetaEvent.MULTICALL_META_TRANSFER_STARTED".

multiCallMetaTransferEnded

public void multiCallMetaTransferEnded(MetaEvent event)

This method indicates that a merge operation has ended, and that no further related events will be reported. See MultiCallMetaEvent.MULTICALL_META_TRANSFER_ENDED for details.

Parameters:

event - A MetaEvent with eventID "MultiCallMetaEvent.MULTICALL_META_TRANSFER_ENDED".