|
JSR-043: JTAPI-1.4 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
The Event
interface is the parent of all JTAPI event interfaces.
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 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.
Event.getCause()
method returns this cause value. The different
types of cause values are also defined in this interface.
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.
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) |
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 |
public static final int CAUSE_NORMAL
public static final int CAUSE_UNKNOWN
public static final int CAUSE_CALL_CANCELLED
public static final int CAUSE_DEST_NOT_OBTAINABLE
public static final int CAUSE_INCOMPATIBLE_DESTINATION
public static final int CAUSE_LOCKOUT
public static final int CAUSE_NEW_CALL
public static final int CAUSE_RESOURCES_NOT_AVAILABLE
public static final int CAUSE_NETWORK_CONGESTION
public static final int CAUSE_NETWORK_NOT_OBTAINABLE
public static final int CAUSE_SNAPSHOT
Method Detail |
public int getCause()
public int getID()
public java.lang.Object getSource()
java.util.EventObject
).
public MetaEvent getMetaEvent()
|
JSR-043: JTAPI-1.4 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |