javax.telephony
Interface Event

All Known Subinterfaces:

ACDAddressEvent, AddressEvent, AgentTerminalEvent, CallCenterCallEvent, CallCenterConnectionEvent, CallCenterEvent, CallCenterTrunkEvent, CallControlAddressEvent, CallControlCallEvent, CallControlConnectionEvent, CallControlEvent, CallControlTerminalConnectionEvent, CallControlTerminalEvent, CallEvent, ConnectionEvent, MetaEvent, MobileProviderEvent, MobileRadioEvent, MultiCallMetaEvent, PhoneTerminalEvent, PrivateDataEvent, ProviderEvent, SingleCallMetaEvent, TerminalConnectionEvent, TerminalEvent

public interface Event

The Event interface is the parent of all JTAPI event interfaces.

Introduction

All JTAPI event interfaces extend this interface, either directly or indirectly. Event interfaces within each JTAPI package are organized in a hierarchical fashion. The architecture of the core package event hierarchy is described later.

The JTAPI event system notifies applications when changes in various JTAPI object occur. Each individual change in an object is represented by an event sent to the appropriate Listener.

In the spirit of the JDK 1.1 Event model changes , JTAPI now has Listeners instead of Observers. In addition to the JDK 1.1 change in terminology, JTAPI event handling has been modified to make programming easier, by multiplexing specific events out to specific methods and by reducing the number of event objects involved. In addition, the memory footprint of the API has been lessened by reducing the number of interfaces defined, in order to accomodate smaller platforms.

JTAPI events will be delivered to a Listener one at a time, unlike the Observer model, where they are delivered in an array.

With the old observer event model, large scale activities such as 3rd party call transfer and conference, are awkward to detect and process.

With the new Listener model and meta events (see MetaEvent), an application has a listener interface with methods and events which convey, directly and with necessary details, what applications need to know to respond to higher-level events.

Note: Classes that implement this interface shall follow the EventListener design pattern by extending java.util.EventObject.

Event Identification

Event objects correspond to the JTAPI object which is undergoing a state change; the specific state change is conveyed to the application in two ways.

First, the provider reports the event to a particular method in a particular Listener interface to a listening object; generally the method corresponds to a particular state change.

Second, the event that is presented to the method has an identification integer which indicates the specific state change.

The Event.getID() method returns this identification number for each event. The actual event identification integer values that may be conveyed by the individual event object are defined in each of the specific event interfaces.

Cause Codes

Each events carries a cause or a reason why the event happened. The Event.getCause() method returns this cause value. The different types of cause values are also defined in this interface.

Core Package Event Hierarchy

The core package defines a hierarchy of event interfaces. The base of this hierarchy is the Event interface. Directly extending this interface are those events interfaces for each object which supports an Listener: ProviderEvent, CallEvent, AddressEvent, and TerminalEvent.

Since Connection and TerminalConnection events are reported via the CallListener interface, the ConnectionEvent and TerminalConnectionEvent interfaces extends the CallEvent interface.

The following diagram illustrates the complete core package event structure.

JTAPI 1.2, Observer Model Meta Events

With JTAPI 1.2 & the observer model, "meta information" mechanisms (see Event.java) - event batches, meta codes, and the Event.isNewMetaEvent() method - were used

A. to indicate what, and which, higher-level action an event belongs to

B. to identify which events are associated with a particular update to the call model (implying synchronization points at which queries are reasonable)

C. to convey, implicitly, multi-call event information.

Determining what and which higher-level action is happening with the observer mechanism is indirect - it must be concluded by looking at meta codes and possibly multiple events. Determining when the JTAPI events imply a consistent call state is conveyed by a change between events in the return value of the method "Event.isNewMetaEvent". Conveying information about multiple calls is done implicitly, across multiple events.

For applications to respond to higher-level actions, and to understand the scope of those actions, in the current JTAPI API, they must scan multiple events, inspect meta codes, inspect "isNewMetaEvent" "flag" values and, ultimately, guess that events are related.

Applications would be much simpler if they were given

A. direct notification of high-level actions

B. explicit descriptions of the scope of these actions (calls involved and events included)

JTAPI 1.3, Listener Model Meta Events

This semantic event proposal addresses these needs. It provides an interface with methods and events which convey, directly and with necessary details, what applications need to know to respond to higher-level events.

 MetaEvent
   MultiCallMetaEvent extends MetaEvent
     constants
       MultiCallMetaMergeStart
       MultiCallMetaMergeEnd
       MultiCallMetaTransferStart
       MultiCallMetaTransferEnd
     methods
       Call[] getOldCalls()
       Call   getNewCall()
 

As for Listening for these events, we would add to CallListener

 CallListener
   methods
     MultiCallMetaMergeStarted ( MetaEvent ev )
     MultiCallMetaMergeEnded ( MetaEvent ev )
     MultiCallMetaTransferStarted ( MetaEvent ev )
     MultiCallMetaTransferEnded ( MetaEvent ev )

and, to be able to map an event back to a meta-event, we'd add

 CallEvent
   method
     MetaEvent getMetaEvent() 

which would return null if there were no meta-event associated with this event.

In addition to these interfaces and methods, the following operational principles would apply (currently just one):

    meta events are reported before any corresponding normal events.

These changes are reflected in the current API.

Field Summary

static int	CAUSE_CALL_CANCELLED Cause code indicating the user has terminated call without going on-hook.
static int	CAUSE_DEST_NOT_OBTAINABLE Cause code indicating the destination is not available.
static int	CAUSE_INCOMPATIBLE_DESTINATION Cause code indicating that a call has encountered an incompatible destination.
static int	CAUSE_LOCKOUT Cause code indicating that a call encountered inter-digit timeout while dialing.
static int	CAUSE_NETWORK_CONGESTION Cause code indicating call encountered network congestion.
static int	CAUSE_NETWORK_NOT_OBTAINABLE Cause code indicating call could not reach a destination network.
static int	CAUSE_NEW_CALL Cause code indicating that a new call.
static int	CAUSE_NORMAL Cause code indicating normal operation
static int	CAUSE_RESOURCES_NOT_AVAILABLE Cause code indicating resources were not available.
static int	CAUSE_SNAPSHOT Cause code indicating that the event is part of a snapshot of the current state of the call.
static int	CAUSE_UNKNOWN Cause code indicating the cause was unknown

Method Summary

int	getCause() Returns the cause associated with this event.
int	getID() Returns the id of event.
MetaEvent	getMetaEvent() Returns the MetaEvent associated with this event, or null.
java.lang.Object	getSource() Returns the event source of the event (see java.util.EventObject).

Field Detail

CAUSE_NORMAL

public static final int CAUSE_NORMAL

Cause code indicating normal operation

CAUSE_UNKNOWN

public static final int CAUSE_UNKNOWN

Cause code indicating the cause was unknown

CAUSE_CALL_CANCELLED

public static final int CAUSE_CALL_CANCELLED

Cause code indicating the user has terminated call without going on-hook.

CAUSE_DEST_NOT_OBTAINABLE

public static final int CAUSE_DEST_NOT_OBTAINABLE

Cause code indicating the destination is not available.

CAUSE_INCOMPATIBLE_DESTINATION

public static final int CAUSE_INCOMPATIBLE_DESTINATION

Cause code indicating that a call has encountered an incompatible destination.

CAUSE_LOCKOUT

public static final int CAUSE_LOCKOUT

Cause code indicating that a call encountered inter-digit timeout while dialing.

CAUSE_NEW_CALL

public static final int CAUSE_NEW_CALL

Cause code indicating that a new call.

CAUSE_RESOURCES_NOT_AVAILABLE

public static final int CAUSE_RESOURCES_NOT_AVAILABLE

Cause code indicating resources were not available.

CAUSE_NETWORK_CONGESTION

public static final int CAUSE_NETWORK_CONGESTION

Cause code indicating call encountered network congestion.

CAUSE_NETWORK_NOT_OBTAINABLE

public static final int CAUSE_NETWORK_NOT_OBTAINABLE

Cause code indicating call could not reach a destination network.

CAUSE_SNAPSHOT

public static final int CAUSE_SNAPSHOT

Cause code indicating that the event is part of a snapshot of the current state of the call.

Method Detail

getCause

public int getCause()

Returns the cause associated with this event. Every event has a cause. The various cause values are defined as public static final variables in this interface.

Returns:

The cause of the event.

getID

public int getID()

Returns the id of event. Every event has an id. The defined id of each event matches the object type of each event. The defined id allows applications to switch on event id rather than having to use multiple "if instanceof" statements.

Returns:

The id of the event.

getSource

public java.lang.Object getSource()

Returns the event source of the event (see java.util.EventObject).

Returns:

The object sending the event.

getMetaEvent

public MetaEvent getMetaEvent()

Returns the MetaEvent associated with this event, or null.

Returns:

The MetaEvent corresponding to this event, or null.